SaaS Starter Kit

SaaS Starter Kit is a full-stack boilerplate for building modern SaaS applications using SvelteKit 5, TypeScript, Node.js (Express + TSOA), and MongoDB. It features a type-safe, end-to-end workflow with OpenAPI for robust API contract management, providing a solid foundation for your next project.

A modern, type-safe foundation for your next great idea.

---

Table of Contents

• Core Concept
• Features
• Tech Stack
• Getting Started
• Development Workflow
• Project Structure
• Scripts

---

Core Concept: The OpenAPI-Driven Workflow

This boilerplate is built around a powerful, API-first workflow that ensures your frontend and backend are always in sync. This is achieved using TSOA on the backend and OpenAPI client generation on the frontend.

This approach eliminates boilerplate, prevents runtime errors, and makes development faster and more reliable.

1. Define in Backend: You define your API endpoints, models, and validation rules in the backend controllers (packages/backend) using TypeScript and TSOA decorators.
2. Generate OpenAPI Spec: TSOA automatically generates an openapi.json (or swagger.json) specification from your code. This spec is the single source of truth for your API contract.
3. Generate Frontend Client: The frontend consumes this openapi.json file to automatically generate a fully type-safe API client (packages/frontend/src/lib/open-api-generated).
4. Build with Confidence: Your SvelteKit frontend can now import and use the generated client, with full type-safety and autocompletion for API requests and responses. No more manual fetch calls or type mismatches!

---

Features

This starter kit comes packed with features to get you up and running quickly.

Feature	Backend (Node.js/Express)	Frontend (SvelteKit)
Framework	Node.js, Express	SvelteKit 5
Language	TypeScript	TypeScript
API Specification	✅ TSOA (OpenAPI 3.0 Generation)	✅ OpenAPI Client Generation
Authentication	✅ JWT-based (Register, Login)	✅ Authentication flow & token management
Database	✅ MongoDB (with Mongoose & Typegoose)	-
Styling	-	✅ Tailwind CSS
Data Fetching	-	✅ TanStack Svelte Query
Dependency Injection	✅ tsyringe for loose coupling	-
Error Handling	✅ Centralized middleware	✅ Type-safe error handling
Logging	✅ winston	-
Validation	✅ tsoa runtime validation	-

---

Tech Stack

Area	Technology
Monorepo	Yarn Workspaces
Frontend	SvelteKit, TypeScript, Tailwind CSS, @tanstack/svelte-query
Backend	Node.js, Express, TypeScript, MongoDB (with Mongoose & Typegoose)
API & Tooling	TSOA, OpenAPI, openapi-typescript-codegen, Axios, Winston, tsyringe

---

Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• Yarn (v1)
• A running MongoDB instance (local or cloud-based)

1. Clone the Repository

git clone https://github.com/ernbaltaci/saas-starter
cd saas-starter

2. Install Dependencies

Install all dependencies for both frontend and backend from the root of the project.

yarn install

3. Configure Environment Variables

You need to set up .env files for both the backend and frontend.

For the Backend:

Create a .env file inside packages/backend/.

# packages/backend/.env
MONGODB_URI=mongodb://localhost:27017/saas-starter
JWT_SECRET=your_super_secret_and_long_jwt_secret
CLIENT_URL=http://localhost:5173

For the Frontend:

Create a .env file inside packages/frontend/.

# packages/frontend/.env
VITE_SCHEMA_URL=http://localhost:3000/swagger.json
VITE_API_URL=http://localhost:3000

4. Run the Development Servers

Run the backend and frontend servers concurrently. It's recommended to run them in separate terminal tabs.

Run the Backend: (Terminal 1)

yarn backend:dev

The backend server will start on http://localhost:3000.

Run the Frontend: (Terminal 2)

yarn frontend:dev

The frontend application will be available at http://localhost:5173.

Note: For a streamlined process, consider adding a root dev script in package.json to run both commands at once using concurrently.

---

Development Workflow

The core of this boilerplate is the API-driven development cycle. Whenever you need to add or change an API endpoint, follow these steps:

1. Modify the Backend: Make changes to your controllers in packages/backend/src/. Add new routes, update models, or change validation logic using TSOA decorators.

2. Regenerate API Spec: The backend development server watches for changes and automatically regenerates the packages/backend/src/swagger.json file.

3. Regenerate Frontend Client: With the backend running, run the following command from the project root:

   yarn generate-api

   This command fetches the updated swagger.json and generates a new, type-safe API client in packages/frontend/src/lib/open-api-generated/.

4. Update Frontend Code: Use the newly generated services and types in your SvelteKit components. You'll get full TypeScript support, ensuring your frontend stays perfectly aligned with the backend API contract.

---

Project Structure

This project is a monorepo using Yarn Workspaces.

/
├── packages/
│   ├── backend/          # Node.js, Express, and TSOA API
│   │   ├── src/
│   │   │   ├── auth/     # Authentication logic
│   │   │   ├── user/     # User models, services, controllers
│   │   │   ├── ...       # Other business domains
│   │   │   └── swagger.json # Auto-generated OpenAPI spec (Source of Truth)
│   │   ├── tsoa.json     # TSOA configuration
│   │   └── package.json
│   │
│   └── frontend/         # SvelteKit UI
│       ├── src/
│       │   ├── lib/
│       │   │   └── open-api-generated/ # Auto-generated API client (DO NOT EDIT)
│       │   ├── routes/   # SvelteKit pages and endpoints
│       │   └── ...
│       ├── scripts/
│       │   └── generate-api.js # Script to generate the API client
│       └── package.json
│
├── package.json          # Root package.json with workspace config
└── README.md

---

Available Scripts

Here are the most important scripts you can run from the root directory:

• yarn backend:dev: Starts the backend development server with hot-reloading.
• yarn frontend:dev: Starts the frontend development server with hot-reloading.
• yarn generate-api: Regenerates the frontend API client from the backend's OpenAPI spec.
• yarn build: Builds both frontend and backend for production.

---