Getting Started

This guide will help you set up the Sustentus monorepo on your local machine and start developing.

Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js >= 22.0.0
pnpm >= 10.0.0
Git

Verifying Prerequisites

You can verify your installations by running:


node --version  # Should be >= 22.0.0
pnpm --version  # Should be >= 10.0.0
git --version

Installation

1. Clone the Repository


git clone <repository-url>
cd sustentus

2. Install Dependencies

The monorepo uses pnpm workspaces. Install all dependencies with a single command:


pnpm install

This will install dependencies for all applications and packages in the monorepo.

3. Set Up Environment Variables

Environment variables for all applications are managed through Vercel. To set up your local environment:

Step 1: Log in to Vercel


pnpm vercel login

Follow the prompts to authenticate with your Vercel account.

Step 2: Pull Environment Variables

From the repository root, pull all environment variables for every app:


pnpm env:pull

This command will download environment variables from Vercel and create a .env.local in each application directory, e.g.:

apps/web/.env.local — the main platform
apps/marketing/.env.local — marketing site
apps/dashboards/.env.local, apps/docs/.env.local (as configured)

The environment variables include:

Clerk authentication credentials
MongoDB connection string (main platform)
AI Gateway, Ably, Resend, and Vercel Blob keys (main platform)
PostHog analytics keys
Other app-specific configuration

Note: Make sure you have access to the Sustentus Vercel project before running this command.

VS Code Setup (Recommended)

For the best development experience, we recommend using Visual Studio Code with the following configuration files.

Tasks Configuration

Create .vscode/tasks.json in the repository root:


{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-packages",
      "type": "shell",
      "command": "pnpm",
      "args": ["packages:build"],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": [],
      "presentation": {
        "reveal": "silent",
        "panel": "shared",
        "showReuseMessage": false
      }
    },
    {
      "label": "Build Marketing Site",
      "type": "shell",
      "command": "pnpm",
      "args": ["marketing:build"],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": ["$tsc"],
      "group": {
        "kind": "build",
        "isDefault": false
      }
    },
    {
      "label": "Build Docs Site",
      "type": "shell",
      "command": "pnpm",
      "args": ["docs:build"],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": ["$tsc"],
      "group": {
        "kind": "build",
        "isDefault": false
      }
    },
    {
      "label": "Build All",
      "type": "shell",
      "command": "pnpm",
      "args": ["build"],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": ["$tsc"],
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
    {
      "label": "Clean All",
      "type": "shell",
      "command": "pnpm",
      "args": ["clean"],
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": []
    }
  ]
}

Usage: Access via Terminal > Run Task... or Cmd+Shift+B for the default build task.

Launch Configuration

Create .vscode/launch.json in the repository root:


{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Marketing app",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["marketing:dev"],
      "cwd": "${workspaceFolder}",
      "restart": { "delay": 5000, "maxAttempts": 2 },
      "skipFiles": ["<node_internals>/**"],
      "console": "integratedTerminal",
      "nodeVersionHint": 22,
      "internalConsoleOptions": "neverOpen",
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!${workspaceFolder}/node_modules/**"
      ],
      "envFile": "${workspaceFolder}/apps/marketing/.env.local"
    },
    {
      "name": "Docs app",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["docs:dev"],
      "cwd": "${workspaceFolder}",
      "restart": { "delay": 5000, "maxAttempts": 2 },
      "skipFiles": ["<node_internals>/**"],
      "console": "integratedTerminal",
      "nodeVersionHint": 22,
      "internalConsoleOptions": "neverOpen",
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!${workspaceFolder}/node_modules/**"
      ],
      "envFile": "${workspaceFolder}/apps/docs/.env.local"
    },
    {
      "name": "Storybook app",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["storybook:dev"],
      "cwd": "${workspaceFolder}",
      "restart": { "delay": 5000, "maxAttempts": 2 },
      "skipFiles": ["<node_internals>/**"],
      "console": "integratedTerminal",
      "nodeVersionHint": 22,
      "internalConsoleOptions": "neverOpen",
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!${workspaceFolder}/node_modules/**"
      ]
    },
    {
      "name": "All Apps (Dev)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["dev"],
      "cwd": "${workspaceFolder}",
      "restart": { "delay": 5000, "maxAttempts": 2 },
      "skipFiles": ["<node_internals>/**"],
      "console": "integratedTerminal",
      "nodeVersionHint": 22,
      "internalConsoleOptions": "neverOpen",
      "sourceMaps": true,
      "resolveSourceMapLocations": [
        "${workspaceFolder}/**",
        "!${workspaceFolder}/node_modules/**"
      ],
      "envFile": "${workspaceFolder}/.env.local"
    }
  ],
  "compounds": [
    {
      "name": "Marketing + Packages (Dev)",
      "configurations": ["Marketing app"],
      "preLaunchTask": "build-packages",
      "stopAll": true
    }
  ]
}

Usage: Access via Run and Debug panel (Cmd+Shift+D) or press F5 to start debugging.

Workspace Settings

Create .vscode/settings.json in the repository root:


{
  "cSpell.words": ["Sustensus"]
}

Recommended Extensions

Install these VS Code extensions for the best development experience:

ESLint (dbaeumer.vscode-eslint) - Real-time linting
Prettier (esbenp.prettier-vscode) - Code formatting
TypeScript (built-in) - Enhanced TypeScript support
Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss) - Tailwind class autocomplete
MDX (unifiedjs.vscode-mdx) - MDX syntax highlighting
Code Spell Checker (streetsidesoftware.code-spell-checker) - Spell checking

You can install all recommended extensions by creating .vscode/extensions.json:


{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "unifiedjs.vscode-mdx",
    "streetsidesoftware.code-spell-checker"
  ]
}

Running and building

Start all apps with pnpm dev (marketing on 3001, docs on 3003, Storybook on 3002), or run one at a time with pnpm marketing:dev, pnpm docs:dev, or pnpm storybook:dev. Run shared packages in watch mode with pnpm packages:dev (or pnpm ui:dev / pnpm services:dev).

Build everything with pnpm build, or a single target with pnpm marketing:build, pnpm docs:build, pnpm storybook:build, or pnpm packages:build. Use pnpm lint, pnpm format, and pnpm clean for code quality and cleanup.

See the Development guide for the full command reference and workflow.

Next Steps

Learn about the Architecture
Explore the Applications
Understand the Development Workflow
Review the Build System