After you setup your Builder Project, you can use the Space CLI to emulate how your app will run in Space on your local machine. This can help you debug any issues before pushing your app to the internet on Deta Space.
To start your app locally, run the
space dev command in your local project:
If you want to open the app in your browser automatically, use the
--open flag. Note that the
space dev command requires you to provide startup commands for your Micros before it will work, which we will touch on shortly.
In the background,
space dev is doing three things:
- Micro Startup: starts each of your app’s Micros in a separate process, using a command you provide
- Routing Emulation: emulates how Space handles routing for your Micros, allowing you to use a single endpoint in local development
- Data Storage: injects a Data Key so you can use the Deta SDK to store data in your Builder Project, without any setup or key management
Before you can spin up your app locally with
space dev, make sure you have your app setup with a
The Space CLI will use development command(s) you provide in your
Spacefile to start each of your app’s Micros locally, specified by
For static engines and fullstack frameworks like Next, Nuxt and SvelteKit, the CLI will choose the right command automatically. For everything else you’ll need to specify your own
The specified command needs to start a web server that listens on the port specified with the
PORT environment variable. This way the CLI can properly forward requests to the correct Micro.
You can find instructions on how to setup the right
dev command for each engine in the Quickstart Guides.
Deta Space offers persistent data storage in Collections. Collections can be read from and written to using the Deta SDK or HTTP API, and they use a Collection specific Data Key for authentication. Every Space application gets its own Collection.
In Deta Space, authentication between an app and its Collection happens automatically, with a user specific Data Key sitting in the app’s environment.
space dev provides the same experience, automatically generating and injecting a Data Key. The data you save will be stored in your Builder Project in Space.
What this means is that you can use Bases and Drives, without managing any keys in your local environment. If you are using the SDK, just initialize the Deta Object.
Base SDK Code Snippet
If you’re using the HTTP API, pull the environment variable
HTTP API Code Snippet
When you run
space dev all Micros will be started in a separate process and a reverse proxy will make them available through a single endpoint.
In our example
Spacefile from earlier,
space dev starts up both Micros on the port
/api. All requests to
will be proxied byspace dev` to the correct Micro.
This lets you build an entire app (with up to 5 separate Micros) on a single endpoint, just like it is in Deta Space.
You can also trigger Scheduled Actions in your local development server by using the
space dev trigger command. Make sure you have defined a Scheduled Action in your Spacefile and set up the right handler in your Micro.
Let’s assume we have the following
Spacefile that runs a
cleanup action on a schedule:
After starting your development server using either
space dev or
space dev up, you can trigger the action manually using the
space dev trigger command. Just pass the Action’s
id into the command.
This command will call your local Action handler with a mock payload and print the returned response to your console.
If you want to run a one-off script or manually start a development server with managed Data Keys, you can use the
space exec call:
If you run the command from a directory that is linked to a space app, you can omit the
--project flag. If not, you can get your project id by navigating to your project in Builder and clicking on the 3 dots (…) in the top right and selecting “Copy Project ID”.
Some use cases for
space exec include:
- testing Base & Drive locally
- pre-filling your projects Bases & Drives with data
- programmatically interacting with Base & Drive
- …anything you can think of!
If you want to have more control over your development process, you can also split the
space dev process into parts:
- First, start Micros individually using the
space dev upcommand
- Then, start a reverse proxy using the
space dev proxy
For the example above, it would look like this:
Some use cases for this include:
- Running each Micro in a separate terminal window
- Integrating Micros with other development tools (ex: vscode tasks)
space dev command is just a shortcut for the combination of
space dev up and
space dev proxy.
If you do not want to use
space dev for whatever reason, but still need to talk with Bases or Drives in your Builder Project, you can manually create and provide a Data Key. Navigate to the “Develop” tab and then the “Data” sub-tab of your Builder Project. Then click “Data Keys”, and create a new Data Key.
You can set this Data Key into your local development environment as
DETA_PROJECT_KEY, and the SDK will automatically pick the correct key up, both in development and in production, for you and any end users of your app.
⚠️ It is generally a bad practice to embed your Data Key in your code, especially if you want to publish your app. All your App’s users will use your Collection, and data will no longer be separated, breaking the personal cloud model. If you want to create an Interop use case using Data Keys, read more here.