The Builder Instance

What’s the Builder Instance?

Builder Instances are fully functional apps running in Space, tied to a Project. You can use them for a few purposes:

• to test and debug your app on Space before releasing it to the world
• as a flexible personal copy of an app you built for your own use

Builder Instances offer all the features that normal Space apps offer, and are always based on a specific Revision of a Project.

There are a few things to keep in mind if you are using your Builder Instance in production. First, it shares data with your entire project, and second, pushing untested changes can break your live app.

Updating a Builder Instance

Once you have pushed your local project to Builder using space push, Builder will automatically take the newly created Revision and install it in your Builder Instance. The Builder instance is automatically added to your Horizon and can be used like any other app.

Accessing a Builder Instance

From the Horizon

Your Builder Instance will automatically be added to your Horizon. Builder Instances are marked by a purple DEV indicator, and offer the all the Context Menu options of a normal Space app. They offer two additional options:

• Open In Builder: opens your Project within Builder
• Unpin Instance: removes your Builder Instance from the Horizon (you can repin it from Builder)

From Builder

You can also view your Builder instance via your Builder Project under the ”Develop” tab. Clicking the Open Builder Instance will open the instance. There is also an option to pin and unpin your Builder Instance to your Horizon.

Using a Builder Instance

For Testing

The primary use case for the Builder Instance is to test your app before publishing it to others. You can think of it as a staging copy of your app that’s running in Space, where you can ensure everything works as intended. Once you’re happy with your app, you can publish your app and share it with others around the world.

Logs

If your app runs into a runtime error while handling a request, the error logs will be returned in the request’s response. These are accessible from your Builder Project and via the app on Horizon. All runtime logs, including the error logs, are stored for 14 days.

The logs are sorted by time and can be filtered by a specific Micro using the dropdown. They are expandable to the full error stack trace, by clicking on any individual log. Runtime logs can help with debugging Space related errors and mis-configurations of your app.

In Production

You can use your Builder Instance as a personal copy of your app in production, if you like. It has all the same features as any other Space app and is automatically kept up to date with your latest changes, through Revisions.

A few words of caution for this use case — since the Builder instance is automatically kept up to date, changes you push can break your app. Your Builder Instance also shares data with your entire project, including your local development setup.

If you instead want to have a safer environment to run your app without sudden changes, you can create and install releases of your app.

Storing Data

The Builder Instance shares its data with your whole Builder Project, which you can develop against. If you are developing your app locally using space dev, the data will be shared between your local environment and your Builder Instance. You can view and update this data as you use your app from your Builder Project or the app’s context menu on the Horizon (“View Data”).

Environment Variables

Your Builder Instance has access to preset and custom environment variables. You can create environment variables for your app via the Spacefile.

You can update your Builder Instance’s environment variables from your Builder Project or from the App’s context menu on the Horizon (“Settings”).

Domains

Builder Instances have the same Domain features as any Space App. You can access your Built-In Space Domain by opening the app, or from the Instance’s context menu on the Horizon (“Settings”).

Scheduled Actions

Your Builder Instance also runs Scheduled Actions, which you can configure via the Spacefile. You can modify and disable Scheduled Actions, just like with any other app, via your Builder Project or through the Instance’s context menu on the Horizon (“Settings”).