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 Cloud, generate backend code, and run your project locally.​

When using Squid, there are three architectural parts you should know about:

  1. The client application(s) - this is the application that you are developing, and it is not part of Squid. It uses the Squid Client SDK often partnered with a client framework (such as React, Angular, Mobile, or another server).
  2. The Squid cloud server - this server is provided by Squid and is responsible for orchestrating the middle tier by connecting to databases and other integrations, maintaining connected client's state, executing backend functions, and much more.
  3. The application backend - a TypeScript project that is run by Squid alongside the Squid cloud server and is used for customizing the application's backend. It has access to the Squid Backend SDK. This part is developed by you.

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. You can also create the backend project in any other location of your choice.

First, navigate to the root directory of your project. Then, run the init command which you can copy from the Squid Cloud Console's application overview page. To access the correct init 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 might 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
  • package.json - contains the project name and scripts
  • /src/service/example-service.ts - this file can be used to put 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.

Receiving log messages from the core Squid backend​

In some cases, we send log messages from our 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

For now, subscribing to the AI type will enable our backend to send a log message containing the full chat prompt sent to the chatbot provider. Support for QUERY, MUTATION, and other log types will be added in the future.

The start command​

You can develop and test your backend locally in order to make quick modifications and debug it before deploying to Squid Cloud. To run your backend project locally, use the following command:

squid start

This command starts a local version of your backend connected to your dev environment. 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:

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 against the local running backend as if it were in production. You can make changes to both the client and the backend code, and it will reflect immediately. You can also debug both the client and the backend code. If you want to debug your backend, you can use your favorite IDE or the npm run command in inspect mode:

1qnpm run start-squid --inspect

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 integrations for your project under your dev environment, you'll need to re-create these in your prod environment first before deploying. (Making this much easier to do is on our roadmap.)

To deploy your backend code to Squid Cloud, start by navigating to your project's root directory. Then, run the deploy command which you can copy from the Squid Cloud 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 Cloud 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 squid deploy command will read them from the .env file.