Development Workflow

This guide covers the recommended development workflow for building and deploying Insites applications. A good workflow saves time, reduces errors, and gives your team confidence that what goes to production has been properly tested.

Environments

Insites uses a multi-environment setup that separates development from production. You create and manage instances through the Console.

• Local codebase - Your working copy of the project on your machine. This is where you write and edit code. Changes are synced to a development instance in real time using the CLI.
• Staging instance - A testing environment that mirrors production. Use it for QA, client review, or user acceptance testing (UAT). All outbound emails on staging instances are suppressed by default, so you can safely test workflows without accidentally emailing end users.
• Production instance - The live environment that your users interact with. Only deploy code here after it has been tested on staging.

The Development Cycle

A typical development cycle follows this flow:

1. Write code locally. Edit Liquid templates, GraphQL queries, schema definitions, and assets in your local codebase.
2. Sync to your development instance. Run to push changes to your instance in real time. The sync command watches for file changes and sends them to the server as they happen. It feels like working on localhost.
3. Test on staging. When you have a release candidate, deploy to your staging instance using . Run through your test plan, verify workflows, and get client sign-off if needed.
4. Deploy to production. Once staging is verified, deploy the same codebase to your production instance.

Version Control

We recommend using a version control system like Git, though it is not required. All you need to work with Insites is your codebase and an instance to sync or deploy to.

If you use Git, a common workflow is:

• Each developer works on their own branch and syncs to their own development instance.
• Feature branches are merged into the main branch after review.
• The main branch is deployed to staging for testing, then to production for release.

This approach keeps production-ready code separated from work in progress and makes it easy to roll back if something goes wrong.

Debugging

During development, you can monitor your instance in real time using . This streams server-side logs to your terminal, including Liquid errors, GraphQL responses, and background job output. Use the Liquid tag in your code to output custom debug information to this log stream.