Quick Start

Let’s build your first StratusTS application! In this guide, you’ll create a project, add an app, and build a working API endpoint—all in under 10 minutes.

Step 1: Create Your Project

First, create a new StratusTS project:

terminal

st create project my-first-app

This creates a new directory with everything you need to get started.

Navigate into your project:

terminal

cd my-first-app

Step 2: Install Dependencies

Install all required packages:

terminal

pnpm i # or npm install

This will take a minute or two. While it’s running, let’s look at what was created.

Step 3: Explore the Project Structure

Your new project has this structure:

• 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

Understanding Key Files

src/settings.ts - Your configuration center:

src/settings.ts

import type { DatabaseType, SettingsType } from 'stratus-ts';

const PORT = 2000;              // Server port
const APPS = [];                // Installed apps (empty for now)
const DATABASE: DatabaseType = false;  // No database yet
const TEMPLATE_DIR = 'templates';      // Template location


export default {
  PORT,
  APPS,
  DATABASE,
  TEMPLATE_DIR,
} satisfies SettingsType;

src/main.ts - Entry point that starts your server:

src/main.ts

import main from './app'

main()

src/app.ts - Configures and exports your application.

src/app.ts

import { Structure } from 'stratus-ts'

const main = async () => {
  const app = await Structure({})

  const { close } = app.listen((port) => {
      console.log(`server running on port : ${port}`) // this is showen in the terminal
  })

  process.on('SIGINT', close).on('SIGTERM', close)
}

export default main

Step 4: Run Your Server

Start the development server:

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’ll see a welcome message!

Server Running

Keep the server running in this terminal. Open a new terminal tab for the next steps.

Step 5: Create Your First App

Now let’s create an app. Apps are self-contained modules that organize your code.

Open a new terminal tab (keep the server running) and run:

terminal

st create app users

This creates a new users directory with this structure:

• Directorysrc/

  • Directoryusers/

    • controllers.ts # Request handlers
    • routes.ts # URL patterns

Step 6: Register Your App

Open src/settings.ts and add your new app:

src/settings.ts

const APPS = ['users'];  // Add your app here

Your settings file should now look like:

src/settings.ts

import type { DatabaseType, SettingsType } from 'stratus-ts';

const PORT = 2000;
const APPS = ['users'];  // ← Changed!
const DATABASE: DatabaseType = false;
const TEMPLATE_DIR = 'templates';

export default {
  PORT,
  APPS,
  DATABASE,
  TEMPLATE_DIR,
} satisfies SettingsType;

Auto-Registration

StratusTS automatically registers routes from all apps in the APPS array. No manual route configuration needed!

Step 7: Create a Controller

Controllers handle HTTP requests. Open src/users/controllers.ts:

src/users/controllers.ts

import { type ControllerType, ok } from 'stratus-ts';

const listUsers: ControllerType = (question, reply) => {
  // Sample data
  const users = [
  { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
  { id: 3, name: 'Charlie Brown', email: 'charlie@example.com' },
  ];

  reply.status(ok()).json({
    success: true,
    data: users,
  });
};

export { listUsers };

What’s happening here?

• ControllerType provides type safety for request/response
• ok() returns HTTP 200 status code
• reply.json() sends JSON response
• We’re returning a success flag with sample user data

Step 8: Define Your Route

Routes connect URLs to controllers. Open src/users/routes.ts:

src/users/routes.ts

import { Router } from 'stratus-ts';
import { listUsers } from './controllers';
const { routes, route } = Router();

route.get('/users', listUsers);

export default routes;

What’s happening here?

• Router() creates a new router for this app
• route.get('/', listUsers) says “on GET requests to /, run listUsers”

Step 9: Test Your Endpoint

Your server auto-reloads with the changes. Visit:

terminal

http://localhost:2000/users

You should see:

browser

{
  "success": true,
  "data": [
      { "id": 1, "name": "Alice Johnson", "email": "alice@example.com" },
      { "id": 2, "name": "Bob Smith", "email": "bob@example.com" },
      { "id": 3, "name": "Charlie Brown", "email": "charlie@example.com" }
  ]
}

🎉 Congratulations! You just built your first API endpoint with StratusTS!

Step 10: Add More Endpoints

Let’s add an endpoint to get a single user. Update src/users/controllers.ts:

src/users/controllers.ts

import { type ControllerType, ok, notFound } from 'stratus-ts';

  const users = [
      { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
      { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
      { id: 3, name: 'Charlie Brown', email: 'charlie@example.com' },
  ];

  const listUsers: ControllerType = (question, reply) => {
      reply.status(ok()).json({
          success: true,
          data: users,
      });
  };

  // NEW: Get single user
  const getUser: ControllerType = (question, reply) => {
      const { id } = question.params();

      const user = users.find(u => u.id === parseInt(id));

      if (!user) {
          return reply.status(notFound()).json({
              success: false,
              error: 'User not found',
          });
      }

      reply.status(ok()).json({
          success: true,
          data: user,
      });
  };

Update your routes in src/users/routes.ts:

src/users/routes.ts

import { Router } from 'stratus-ts';
import { listUsers, getUser } from './controllers';

const { routes, route } = Router();

route.get('/', listUsers);
route.get('/<id:int>', getUser);  // NEW: Dynamic route

export default routes;

Now test these URLs:

terminal

http://localhost:2000/      → Lists all users
http://localhost:2000/1    → Shows Alice
http://localhost:2000/2    → Shows Bob
http://localhost:2000/999  → Returns 404

Understanding What You Built

Let’s recap what you accomplished:

1. Created a project with StratusTS CLI
2. Created an app to organize code
3. Registered the app in settings
4. Built controllers to handle requests
5. Defined routes to connect URLs to controllers
6. Created a working API with multiple endpoints

All of this in less than 10 minutes, with minimal boilerplate!

What’s Next?

Now that you have a working application, here are your next steps:

Learn More About Apps

Read Creating Apps to understand:

• App architecture in depth
• Best practices for organizing code
• How to create reusable apps

Configure Your Project

Explore Settings Configuration to learn about:

• Changing the server port
• Configuring databases
• Setting up templates
• Adding more apps

Build Real Controllers

Dive into Controllers to discover:

• Handling POST requests with body data
• Working with headers
• Error handling
• Status codes
• Response formats

Work with Databases

When you’re ready for databases, check out:

• Models - Define your data structure
• Database Setup - Configure connections
• Migrations - Manage schema changes

Render HTML Pages

Want to build traditional web pages? See:

• Template Rendering - Use EJS templates

Common Next Steps

Add a POST endpoint:

users/controllers.ts

  import { created } from 'stratus-ts';

const createUser: ControllerType = (question, reply) => {
  const {
      body:{
          name,
          email
      }
  } = await question.body()

  // In real app, save to database
  const newUser = {
      id: Date.now(),
      name,
      email,
  };

  reply.status(created()).json({
      success: true,
      data: newUser,
  });
};


export { listUsers, getUser, createUser };

users/routes.ts

route.post('/create', createUser);

Test with curl:

terminal

curl -X POST http://localhost:2000/create -H "Content-Type: application/json" -d '{"name":"David","email":"david@example.com"}'

Create another app:

terminal

st create app blog

Add to settings:

src/settings.ts

const APPS = ['users', 'blog']; <- add here

Now build blog functionality in the blog app!

Tips for Success

Keep Apps Focused

Each app should handle one domain. Don’t put user management and blog posts in the same app.

Use TypeScript

Take advantage of type safety. Let your IDE autocomplete and catch errors before runtime.

Follow REST Conventions

Use standard HTTP methods: GET for reading, POST for creating, PUT/PATCH for updating, DELETE for removing.

Start Simple

Begin with simple controllers and routes. Add complexity only when needed.

Getting Help

Stuck on something? Here’s where to get help:

• Search this documentation - Use the search bar at the top
• Check examples - Look at the code examples in each guide
• GitHub Issues - Ask questions or report bugs
• GitHub Discussions - Community Q&A

Summary

You’ve now:

• ✅ Created a StratusTS project
• ✅ Built your first app
• ✅ Created controllers and routes
• ✅ Built a working REST API
• ✅ Understand the basic workflow

You’re ready to build real applications with StratusTs!

Continue learning:

• Settings Configuration - Configure your project