Installation

This guide walks you through installing StratusTS and verifying your setup. Let’s get you up and running!

Prerequisites

Before installing StratusTS, ensure you have:

Node.js

• Minimum version: Node.js 16.x or higher
• Recommended: Node.js 18.x or later
• Check your version: node --version
• Download Node.js if needed

Package Manager

• npm (comes with Node.js) or
• pnpm (recommended for faster installs)
• yarn also works

TypeScript Knowledge

• Basic understanding of TypeScript
• Familiarity with types and interfaces
• Understanding of async/await

Optional but Helpful

• Experience with Express or similar frameworks
• Familiarity with Django’s architecture
• Basic database knowledge

Installation Methods

Method 1: Global Installation (Recommended)

Installing globally gives you access to the st command anywhere on your system.

Using pnpm:

terminal

pnpm add -g stratus-ts

or,

Using npm:

terminal

npm install -g stratus-ts

or,

Using yarn:

terminal

yarn global add stratus-ts

This installs the stratus-ts CLI globally, allowing you to run commands like st create project from any directory.

Verify Installation

After installing, verify stratus-ts is accessible:

terminal

st --version

or

terminal

stratus-ts --version

You should see the current version number, like 0.1.0.

If you see “command not found,” check the Troubleshooting section below.

Your First Project

Once installed, create your first project:

terminal

st create project my-first-app

This command:

1. Creates a new directory called my-first-app
2. Sets up the project structure
3. Generates configuration files
4. Creates initial source files

You’ll see output like:

terminal

✓ Creating project directory...
✓ Generating package.json...
✓ Setting up TypeScript configuration...
✓ Creating source files...
✓ Project created successfully!

Next steps:
 cd my-first-app
 npm install
 npm run dev

Install Dependencies

Navigate to your project and install dependencies:

terminal

cd my-first-app
pnpm i # or npm install

This installs all required packages including:

• TypeScript compiler
• stratus-ts runtime
• Development tools

Start Development Server

Run your application in development mode:

terminal

pnpm dev # or npm run dev

You should see:

terminal

server running on port : 2000

Open your browser and visit http://localhost:2000. You should see a welcome message!

Project Structure

After installation, your project looks like this:

• Directorymy-first-app/

  • Directorynode_modules/ # Installed dependencies

    • …
  • Directorysrc/ # Your application code

    • app.ts # App setup
    • main.ts # Entry point
    • settings.ts # Configuration
  • package.json # Dependencies and scripts
  • tsconfig.json # TypeScript configuration

Key Files Explained:

package.json
Defines your project dependencies and scripts. Contains commands like npm run dev and npm run build.

tsconfig.json
Configures how TypeScript compiles your code. Pre-configured with optimal settings.

src/app.ts
Sets up your StratusTS application. Registers apps and configures the server.

src/main.ts
The entry point. Imports your app configuration and starts the server.

src/settings.ts
Central configuration for port, database, apps, and templates. Learn more about settings.

Available Scripts

Your project comes with several npm scripts:

Development:

terminal

pnpm dev # or npm run dev

Runs the application in development mode with hot reloading.

Build:

terminal

pnpm build # or npm run build

Compiles TypeScript to JavaScript for production.

Start:

terminal

npm start # prefer because pnpm is over kill for prod

Runs the compiled production build.

Troubleshooting

Command Not Found

If st or stratus-ts isn’t recognized:

On Linux/macOS:

1. Check npm global bin path:

   terminal

   npm config get prefix

2. Ensure this path is in your $PATH. Add to ~/.bashrc or ~/.zshrc:

   terminal

   export PATH="$PATH:$(npm config get prefix)/bin"

3. Reload your shell:

   terminal

   source ~/.bashrc  # or ~/.zshrc

On Windows:

1. Check global installation directory:

   terminal

   npm config get prefix

2. Add this path to your system’s PATH environment variable:

   • Search for “Environment Variables” in Start menu
   • Edit “Path” under System Variables
   • Add the npm prefix path

Alternative: Use the full path:

terminal

npx stratus-ts create project my-app

Permission Errors (Linux/macOS)

If you get EACCES permission errors:

Option 1: Fix npm permissions (recommended)

terminal

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Then reinstall:

terminal

npm install -g stratus-ts

Option 2: Use sudo (not recommended)

terminal

sudo npm install -g stratus-ts

Port Already in Use

If port 2000 is busy, change it in src/settings.ts:

src/settings.ts

const PORT = 3000; // Use any available port

TypeScript Errors

Ensure you have compatible TypeScript version:

terminal

pnpm i -D typescript # or npm install -D typescript

Module Not Found

If imports fail, regenerate dependencies:

terminal

rm -rf node_modules package-lock.json
npm install

Slow Installation

If npm install is slow:

Use pnpm (faster):

terminal

npm install -g pnpm
pnpm install

Or enable npm cache:

terminal

npm config set cache ~/.npm-cache --global

Updating StratusTS

To update to the latest version:

Global installation:

terminal

npm update -g stratus-ts

Check for updates:

terminal

npm outdated -g stratus-ts

Install specific version:

terminal

npm install -g stratus-ts@0.2.0

Uninstalling

To remove StratusTS:

Global uninstallation:

terminal

npm uninstall -g stratus-ts

Remove projects (be careful!):

terminal

rm -rf my-first-app

Next Steps

Installation complete! Here’s what to do next:

Quick Start Guide - Build your first endpoint

Need help? Check GitHub Issues or Discussions.