/jetstream

A better way to work on Salesforce

Primary LanguageTypeScriptGNU Lesser General Public License v3.0LGPL-3.0

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 OPEN SOURCE AND FREE TO USE. IF YOUR COMPANY IS GETTING VALUE, PLEASE CONSIDER SPONSORING THE PROJECT ❤️

There are multiple ways to use Jetstream.

  1. Use the hosted version at https://getjetstream.app
  2. Use the desktop version TODO: COMING SOON
  3. Run locally
    1. Using nodejs
      1. Building yourself (recommended if you want to contribute to the Jetstream codebase)
      2. Using the pre-built version TODO: COMING SOON
    2. Using Docker
  4. 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)
│   ├── download-zip-sw
│   ├── electron (DESKTOP APPLICATIONS)
│   │   ├── jetstream (DESKTOP BACKEND)
│   │   ├── preferences (DESKTOP PREFERENCES)
│   │   └── worker (DESKTOP WORKER - REPLACES API BACKEND NODE SERVER)
│   ├── jetstream (FRONTEND REACT APPLICATION)
│   ├── jetstream-e2e
│   ├── jetstream-worker
│   ├── landing (LANDING PAGE WEBSITE)
│   ├── landing-e2e
│   ├── maizzle (EMAIL TEMPLATE GENERATION)
│   └── ui-e2e
├── build (DESKTOP BUILD)
├── custom-typings
├── dist (FOLDER CREATED ONCE APPLICATION IS BUILT)
├── electron-scripts
├── libs (CORE LIBRARIES SHARED ACROSS ALL APPLICATIONS)
│   ├── api-config
│   ├── api-interfaces
│   ├── 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 16 or 18 installed.
  2. If you want to run the dev server, make sure you have yarn installed.

📓 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.

The easiest way to run Jetstream locally is to download the pre-built and transpiled javascript files and run them using NodeJs.

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

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.

Download pre-built application

This is the fastest 🏃 way to run Jetstream locally.

TODO: instructions to download and instructions to run

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 16+
    • Version 18 is preferred, but 16 will work.
  • Install Yarn
  • Install dependencies
    • Run yarn to install all dependencies
  • Initialize .env file
    • yarn 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
      • yarn build (this may take some time - if the build is cached in the cloud, this may run quickly)
    • Start Jetstream
      • yarn db:migrate to initialize database
      • yarn 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
      • yarn build:landing
      • yarn build:sw
      • yarn db:generate
    • Start Jetstream
      • terminal 1: yarn start:api to start api server
        • This runs on http://localhost:3333 - most endpoints are prefixed at the /api path
      • terminal 2: yarn start to start api server
        • This runs on http://localhost:4200 and you will need to access the application here http://localhost:4200/app
    • Optional

Start Jetstream (with docker)

⚠️ Docker requires a computer with substantial resources.

  1. Make sure you have Docker Desktop installed
  2. Download the pre-built version of the application here TODO:
    1. Optionally you can build from sources, following the steps above 👆
  3. 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

Desktop Application

TODO: THIS HAS NOT BEEN ENTIRELY WORKED OUT YET

Local development

  • Start jetstream local server
    • yarn start
  • Start electron-worker in watch mode (background renderer - rebuild on changes)
    • yarn start:electron-worker
  • Start electron app
    • yarn start:electron

Packaging

Packaging can only be done by resources that have access to the Apple Developer account.

  1. Ensure the following environment variables are set
    1. APPLE_ID, APPLE_ID_PASSWORD, APPLE_TEAM_ID, GH_TOKEN
  2. Ensure all the certificates are installed
    1. Login to apple.developer
    2. Download each certificate
    3. install in system keychain
    4. OR - if that does not work, open xcode > preferences > accounts > Manage certificates > Add App and Developer certificate
  3. Build application using Desktop build
    1. yarn build:electron
    2. Run yarn electron:package:concurrently
      1. Or run each command individually if testing specific build yarn electron:dist:macos, yarn electron:dist:macos-arm64, yarn electron:dist:win

Signing resources