Skip to content

CodySwannGT/SaasStarter

BranchesTags

Repository files navigation

SaaS Starter Kit: Monorepo Edition

License: MIT

Welcome to the SaaS Starter Kit! This project provides a comprehensive, production-ready foundation for building modern, scalable Software-as-a-Service (SaaS) applications. It features a monorepo structure powered by Turborepo and Bun, a universal frontend application built with React Native/Expo, a robust NestJS backend with GraphQL, and infrastructure-as-code using AWS CDK.

✨ Core Features

  • Monorepo Architecture: Managed with Turborepo and Bun for optimized builds, efficient dependency management, and a streamlined developer experience across multiple packages and applications.
  • Universal Frontend: A single React Native codebase using Expo to build applications for iOS, Android, and the Web.
  • Scalable Backend: A NestJS API built with:
  • Authentication: Secure user authentication and management via AWS Cognito.
  • Infrastructure as Code (IaC): Manage and deploy your AWS infrastructure repeatably and reliably using the AWS CDK (Cloud Development Kit).
  • Developer Experience:
    • End-to-end TypeScript for robust type safety.
    • Pre-configured linting with ESLint and code formatting with Prettier.
    • Shared configurations for TypeScript, ESLint, and Prettier located in the packages/ directory.
    • Unit and integration testing setup with Jest.
  • (Planned) Multi-Tenancy: Architectural considerations for organization-based multi-tenancy.
  • (Planned) Role-Based Access Control (RBAC): Foundation for a flexible permission system.

🛠️ Technology Stack

🚀 Getting Started

Prerequisites

Ensure the following tools are installed and configured on your system:

  • Bun: v1.0.0 or higher.
  • Node.js: v18 or v20 (LTS versions recommended). Use nvm to manage Node versions.
  • Git: For version control.
  • Docker: For running local development services (e.g., PostgreSQL database for the backend).
  • AWS CLI: Configured with appropriate AWS credentials.
  • AWS CDK Toolkit: v2 or higher (npm install -g aws-cdk).

Installation & Setup

  1. Clone the Repository:

    git clone https://github.com/your-org/saas-starter.git my-saas-app
cd my-saas-app

    (Replace your-org/saas-starter.git with your actual repository URL)

  2. Install Dependencies: From the root of the monorepo, run:

    bun install

    This installs dependencies for all workspaces.

  3. Environment Configuration:

    • Root .env: Copy .env.example to .env at the project root. Update with TURBO_TOKEN and TURBO_TEAM if using Turborepo Remote Caching.
    • Frontend (apps/frontend):
      • Copy apps/frontend/.env.example to apps/frontend/.env.local (for local development).
      • Set EXPO_PUBLIC_GRAPHQL_BASE_URL (e.g., http://localhost:3000/graphql or your deployed backend URL).
      • Update EXPO_PUBLIC_SENTRY_DSN if using Sentry.
      • Important: Update the EAS Project ID in apps/frontend/eas.json and potentially in apps/frontend/app.config.ts.
    • Backend (apps/backend):
      • Copy apps/backend/.env.example to apps/backend/.env.dev (used by serverless-offline).
      • Set DATABASE_URL (e.g., postgresql://postgres:postgres@localhost:5432/saas_starter_db for the local Docker setup).
      • COGNITO_USER_POOL_ID and COGNITO_CLIENT_ID will be outputs from your Cognito CDK stack deployment.
      • Update SENTRY_DSN if using Sentry.

  4. AWS Setup (for cloud deployments):

    • Configure your AWS CLI with SSO or IAM credentials: aws configure sso (recommended) or aws configure.
    • If your organization uses an AWS VPN for specific environments, ensure it's connected.

  5. (Optional) Local Database with Docker: A docker-compose.yml is provided in apps/backend/ for a local PostgreSQL instance.

    # From the apps/backend directory
docker-compose up -d

🏗️ Project Structure

The monorepo is organized to promote separation of concerns and scalability:

  • apps/: Contains the deployable applications.
    • frontend/: Expo universal application (iOS, Android, Web).
    • backend/: NestJS GraphQL API.
  • docs/: Project-level documentation, including architecture, development guides, and decision records.
    • CONTRIBUTING.md: Guidelines for contributing.
    • (Links to other key documents like CODING_STANDARDS.md, WORKFLOWS.md will be added here as they are created).
  • infrastructure/: AWS CDK code for defining and provisioning cloud infrastructure. See infrastructure/README.md.
  • packages/: Shared TypeScript packages.
  • scripts/: Utility scripts for automation and development tasks. See scripts/README.md.

💻 Development Workflow

Execute commands from the root of the monorepo using bun run <script>.

Core Monorepo Scripts

  • Start all apps in development mode: bun run dev
  • Lint all code: bun run lint
  • Format all code: bun run format
  • Run all tests: bun run test
  • Build all apps and packages: bun run build
  • Type check all packages: bun run typecheck
  • Clean build artifacts & caches: bun run clean

Application-Specific Development

  • Frontend:
    • Dev server (Expo Go, Web): bun run dev:frontend or bun run dev:web
    • iOS simulator: bun run dev:ios
    • Android emulator: bun run dev:android
    • Environment-specific start: bun start:local-frontend (see apps/frontend/README.md)
    • Generate GraphQL types: bun generate:types:frontend
  • Backend:
    • Dev server (NestJS + Serverless Offline): bun run dev:backend
    • GraphQL Playground/Sandbox: http://localhost:3000/graphql (or configured port)
    • Generate GraphQL schema/types: cd apps/backend && bun run generate:typings
    • Database migrations: cd apps/backend && bun run migration:run:local (or migration:run for cloud)

Refer to individual app READMEs in apps/ for more detailed commands.

🛠️ Tooling & IDE

  • VS Code: Recommended. Install workspace-recommended extensions (prompt on open or check .vscode/extensions.json). Key extensions include ESLint, Prettier, GraphQL, Apollo Client Devtools, Jest.
  • Prettier: Configured via packages/prettier-config. Enable "Format on Save" in VS Code.

📦 Shared Configurations

Shared configurations ensure consistency across the monorepo:

See each package's README for usage details.

☁️ Deployment

  • Infrastructure (AWS CDK): From infrastructure/: 
    cd infrastructure
# bun run cdk bootstrap --profile <aws-profile> # If first time
bun run deploy:<dev|staging|prod>
  • Backend API (Serverless Framework): From apps/backend/: 
    cd apps/backend
bun run deploy:<dev|staging|prod>
  • Frontend App (Expo EAS): From apps/frontend/: 
    cd apps/frontend
eas build -p <android|ios|all> --profile <development|preview|production>
eas submit -p <ios|android> --profile <production> --latest
    Web builds (bun run build:web in apps/frontend) are deployed to static hosting.

🤝 Contributing

Contributions are welcome! Please review our CONTRIBUTING.md for guidelines on commit messages, the PR process, coding standards, and more. (Note: CONTRIBUTING.md will be created/populated with content moved from apps/backend/README.md in a separate step/task).

📚 Further Documentation

🧰 Troubleshooting

  • Stale Cache/Build Issues: 
    bun run clean
rm -rf node_modules bun.lockb apps/*/node_modules apps/*/bun.lockb packages/*/node_modules packages/*/bun.lockb
bun install
  • Type Errors: Run bun run typecheck to identify TypeScript issues.
  • Environment Variables: Double-check .env files in the root and app directories.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.# SaasStarter

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages