Jetstream

A better way to work on Salesforce

The Jetstream platform makes managing your Salesforce instances a breeze. Use Jetstream to work with your data and metadata to get your work done faster.

Learn more by reading the docs.

JETSTREAM IS SOURCE-AVAILABLE AND FREE TO USE. IF YOUR COMPANY IS GETTING VALUE, CONSIDER SPONSORING THE PROJECT ❤️

Jetstream wouldn't be possible without your contributions.

There are multiple ways to use Jetstream.

1. Use the hosted version at https://getjetstream.app
2. Run locally
   1. Using nodejs
      1. Building yourself (recommended if you want to contribute to the Jetstream codebase)
   2. Using Docker
3. Want to self-host behind your company firewall? Reach out to the team for assistance.

Overview of the codebase structure

This project was generated using Nx - This repository is considered a mono-repo and has multiple applications

├── app (This is used in the generation of the desktop application)
├── apps (Application)
│   ├── api (BACKEND NODE SERVER)
│   ├── cron-tasks
│   ├── docs (DOCS WEBSITE)
│   ├── jetstream (FRONTEND REACT APPLICATION)
│   ├── jetstream-e2e
│   ├── jetstream-worker
│   ├── landing (LANDING PAGE WEBSITE)
│   ├── maizzle (EMAIL TEMPLATE GENERATION)
│   └── ui-e2e
├── custom-typings
├── dist (FOLDER CREATED ONCE APPLICATION IS BUILT)
├── libs (CORE LIBRARIES SHARED ACROSS ALL APPLICATIONS)
│   ├── api-config
│   ├── connected (FRONTEND DATA LIBRARY)
│   ├── icon-factory (SFDC ICONS)
│   ├── monaco-configuration
│   ├── shared (SHARED UTILS ETC..)
│   ├── splitjs
│   ├── types (TYPESCRIPT TYPES)
│   └── ui (ANYTHING UI RELATED)
├── prisma (DB MIGRATIONS)
│   └── migrations
├── scripts
└── tools
    └── generators

Getting Started

Running Locally

IF YOU HAVE ANY ISSUES WITH THE STEPS BELOW, PLEASE FILE A TICKET.

Pre-req

1. Make sure you have node 24 installed.
2. If you are using docker, make sure you have Docker installed.
3. If you want to run the dev server, make sure you have pnpm installed. Corepack is recommended.

Installing Dependencies

Setting up your environment

Run this script to copy .env.example to .env which will generate encryption keys which are required to run the application. You will be asked some questions which will determine some of the environment variables.

pnpm scripts:generate-env

📓 You can choose to skip authentication locally by setting the environment variable EXAMPLE_USER_OVERRIDE=true. This is set to true by default in the .env.example file. 🌟 To use this, don't click the login button, but instead just go to http://localhost:3333/app or http://localhost:4200/app (if running the react development server) directly.

Using Docker

If you have docker and just want to run the application locally, using docker is the easiest option.

Build the docker image (this takes a while the first time).

docker build -t jetstream-app .

Use docker compose to create a dockerized postgres database and run the app.

docker compose up

• Jetstream will be running at http://localhost:3333
• Postgres will be running on port 5555 if you wanted to connect to it locally.
• You can login with the Example user
  • The username is test@example.com
  • The password is contained in the .env file
• If assets on the page don't load, do a hard refresh (hold cmd or shift and press refresh)
  • This might happen if you have re-built the image and the browser has cached the page with now missing resources.

Running without Docker

Use this option if you want to contribute to the codebase.

Jetstream relies on a Postgres database, so you either need to run Postgresql locally, in a docker container, or use a managed provider such as one from the list below. Optionally you can run jetstream in a Docker container which includes Postgresql.

• Render (Jetstream is hosted here)
• elephantsql
• AWS
• Azure
• GCP

You can use the example Salesforce OAuth2 client secret or client id, but you are welcome to create you own connected app in any Salesforce org of your choice.

If you want to create your own:

1. Login to any org where you are an admin, usually a developer org or production org is best
2. Setup > App Manager > New Connected App
   1. name it whatever you want
   2. Click "Enable OAuth Settings"
      1. Callback URL: http://localhost:3333/oauth/sfdc/callback
      2. Scopes:
         1. Access the identity URL service id, profile, email, address, phone
         2. Access unique user identifiers openid
         3. Manage user data via APIs api
         4. Perform requests at any time refresh_token, offline_access
      3. All other defaults are fine
3. Update the file named .env and replace SFDC_CONSUMER_KEY and SFDC_CONSUMER_SECRET with the values from your connected app.

Building

⭐ If you want to contribute to Jetstream, this is the best option.

Configure environment

• Install postgres
  • ensure this is running with a database called postgres and a user named postgres on default port 5432
    • If your database is cloud hosted or named something different, then you can adjust the environment variable in .env after you initialize your application and this file is created.
• Install node 24
• Enable Corepack
  • Run corepack enable
• Install dependencies
  • Run pnpm install to install all dependencies
• Initialize .env file
  • pnpm init:project (or manually copy .env.example to .env)
  • If you need to adjust your postges connection, you can do so now.
• Running in production mode
  • Build application
    • pnpm build (this may take some time - if the build is cached in the cloud, this may run quickly)
  • Start Jetstream
    • pnpm db:migrate to initialize database
    • pnpm db:seed to insert required records for the application
    • node dist/apps/api/main.js
    • Visit in a web browser - TODO: allow skipping auth
      • http://localhost:3333/app
• Running in development mode - use this option if you want to work with the codebase
  • Build required applications
    • pnpm build:landing
    • pnpm db:generate
  • Start Jetstream
    • terminal 1: pnpm start:api to start api server
      • This runs on http://localhost:3333 - most endpoints are prefixed at the /api path
    • terminal 2: pnpm start to start the web development server
      • This runs on http://localhost:4200 and you will need to access the application here http://localhost:4200/app
      • The port is chosen at startup and printed in the terminal. If 4200 is taken the next server picks 4210, then 4211, and so on, so several git worktrees can run a development server at the same time against the one api server. See Running several worktrees at once.
  • Optional
    • pnpm start:ui:storybook to start the storybook server
      • This runs on http://localhost:4400
      • You can check out the public version of this at https://storybook.getjetstream.app

Running several worktrees at once

Only one api server is needed no matter how many copies of the repo you have checked out. Start it once with pnpm start:api, then run pnpm start in each worktree you want a web development server for. Every development server proxies /api, /oauth, /socket.io and friends to that shared api server, so they all share one login session, one database and one set of connected Salesforce orgs — switching between them requires no logging in and no .env changes.

Ports are assigned automatically: the first server started takes 4200, and any others take 4210, 4211 and upwards. 4201-4209 are never used, so they stay free for the desktop client (4201) and canvas (4202) development servers.

Two environment variables override this when needed:

• JETSTREAM_DEV_PORT - pin the development server to a specific port instead of searching for a free one
• JETSTREAM_DEV_API_URL - proxy to an api server other than http://localhost:3333

Giving a worktree its own api server is deliberately not supported. Connected orgs are stored against JETSTREAM_SERVER_URL, so a second api server on a different port sees an empty org list and every org has to be re-authorized, and the Salesforce and Google OAuth callback urls are registered against a specific port.

Start Jetstream (with docker)

⚠️ Docker requires a computer with substantial resources.

1. Make sure you have Docker Desktop installed
2. Run docker compose up in your terminal
   1. This may take a while the very first time
   2. If you make any changes, you need to re-build the application using docker compose build