Skip to main content

Local development and CLI

Developing locally with Squid allows you to test your application and make changes to your code before deploying to production.​

The Squid CLI (Command Line Interface) provides an easy way to communicate with Squid, generate backend code, and run your project locally.

When developing with Squid, there are two architectural components you manage within your application:

  1. The client application(s) - this is the client application or frontend that you are developing. It uses the Squid Client SDK often partnered with a client framework (such as React, Angular, mobile, etc.).
  2. The application backend - a TypeScript project that is run by Squid and is used for customizing the application's backend. It has access to the Squid Backend SDK.

To develop locally, you first need to create a backend project using the Squid CLI.

Installation​

In order to install the CLI, execute the following npm command:

npm install -g @squidcloud/cli

If you see permission errors, please read npm's official guide.

The init command​

To create a new backend project for your application, use the init command.

Navigate to the root directory of your project and run the squid init command. You can copy the full command from the Squid Console's application overview page. To access the command, click the Initialize Backend button in the console. The console automatically generates the proper command with the correct values for your account and application.

The command will look like this:

cd YOUR_APP_DIRECTORY
squid init YOUR_APP_NAME-backend --appId YOUR_APP_ID --apiKey YOUR_API_KEY --environmentId TARGET_ENVIRONMENT_ID --squidDeveloperId YOUR_SQUID_DEVELOPER_ID --region YOUR_REGION

After executing the command, the following key files will be generated inside the newly created backend directory:

  • .env - contains your application ID, region, Squid Developer ID, and environment ID. These values are required for local development. This file can be generated separately by using the squid init-env command (which can also be found in the Squid Console).
  • /src/service/example-service.ts - this file can be used as a starting point for your backend code.
Important

Your .env file, which contains sensitive information and is unique to each developer, will automatically be added to your .gitignore file. To ensure the security and integrity of your development environment, please avoid including this file in your version control system.

The start command​

You can develop and test your backend locally in order to make quick modifications and debug it before deploying to Squid. To run your backend project locally, use the following command. This command starts a local version of your backend connected to your dev environment:

squid start

After running this command, you can initialize your Squid client application to communicate with your local backend by setting the environmentId: 'dev' and squidDeveloperId: YOUR_SQUID_DEVELOPER_ID options. This exact code may vary depending on your client application:

Client code
import { Squid } from '@squidcloud/client';

const squid = new Squid({
  appId: 'YOUR_APP_ID',
  region: 'YOUR_REGION', // example: 'us-east-1.aws'
  environmentId: 'dev',
  squidDeveloperId: 'YOUR_SQUID_DEVELOPER_ID',
});

At this point, the client application can run alongside and communicate with your local backend. You can make changes to both the client and the backend code and test your changes immediately.

Extend backend logging​

In some cases, Squid sends log messages from Squid's core backend to your local backend. To enable seeing these messages, you must subscribe to the types of messages you want to receive. This is done by setting the SQUID_LOG_TYPES environment variable in the .env file you just created. The available log types are: ALL, QUERY, MUTATION, AI, API and ERROR with more coming in the future. They may be combined in any order and separated by a comma:

SQUID_LOG_TYPES=QUERY,MUTATION,AI,API,ERROR

The deploy command​

Deploying your backend can be done in either the dev or prod environments. Deploying to dev allows you to test how your backend will function once it goes live. You can still make changes to your backend, but you will need to redeploy to activate those changes.

Once you are ready to push your project to production, you can use the squid deploy command. Before executing the deploy command, ensure that your environmentId attribute is set to prod in your client code configuration. You should also delete the squidDeveloperId option for production use.

Tip

If you've created any connectors for your project under your dev environment, you'll need to re-create these in your prod environment first before deploying.

To deploy your backend, start by navigating to your project's root directory. Then, run the deploy command which you can copy from the Squid Console's application overview page. To access the correct deploy command, click the Deploy Backend button in the console. The console automatically generates the proper command with the correct values for your account and application. The command will look something like this:

squid deploy --apiKey YOUR_API_KEY --environmentId TARGET_ENVIRONMENT_ID

After the successful deployment, the Squid Console should reflect an updated list of your backend functions. Access this feature in the backend section of the Console.

Note

Should the parameters not be provided in the command line, the deploy command will read them from the .env file.