Skip to content

swarm-wasp-starter

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

swarm-wasp-starter

README.md

Swarm Wasp Starter

A production-ready Wasp starter template powered by the Swarm code generation framework.

Overview

This starter template demonstrates how to build modern Wasp applications using Swarm's code generation functionality. It's designed as a foundation for creating starter templates rather than a complete application, providing minimal but well-structured code that showcases Swarm's features.

Built with:

  • Swarm generator framework for dynamic code generation
  • Swarm Wasp plugin for Wasp-specific generators
  • Feature-based architecture with consistent directory structure and file content
  • Type-safe Wasp configuration with fluent API
  • shadcn/ui components and Tailwind CSS for styling
  • MCP integration for AI-assisted development

What's Included

  • Enhanced App Class: Fluent API for Wasp configuration with helper methods
  • Feature-Based Structure: Organised directory layout implemented by the Swarm Wasp plugin
  • Swarm Generators: All generators available for rapid development
  • Development Scripts: Comprehensive npm scripts for Wasp workflows
  • MCP Integration: Ready for AI-assisted development
  • Modern UI: shadcn/ui components with Tailwind CSS
  • Type Safety: Complete TypeScript support throughout

Directory Structure

The template implements the feature-based directory structure defined by the Swarm Wasp plugin:

src/
├── features/
│   └── root/                    # Example feature
│       ├── root.wasp.ts         # Feature configuration
│       └── client/
│           └── pages/
│               └── Home.tsx     # Example page component
├── shared/
│   └── client/
│       ├── components/          # Shared React components
│       │   ├── Layout.tsx       # Main layout component
│       │   ├── Header.tsx       # Header component
│       │   ├── Footer.tsx       # Footer component
│       │   └── ui/              # shadcn/ui components
│       ├── hooks/               # Custom React hooks
│       │   ├── useTheme.tsx     # Theme management
│       │   └── useMobile.ts     # Mobile detection
│       └── lib/
│           └── utils.ts         # Utility functions
├── main.wasp.ts                 # Main Wasp configuration
└── schema.prisma                # Database schema

Getting Started

Prerequisites

  • Node.js 24.14.1+
  • npm
  • Wasp 0.24.x

Installation

  1. Create a new project from this template:

    npx @ingenyus/swarm create my-app --template genyus/swarm-wasp-starter

  2. Navigate to your project:

    cd my-app

  3. Install and configure dependencies:

    npm run reset:wasp

  4. Start the development server:

    npm run dev

Generating Code

Comprehensive Example

Let's build a complete user management feature to demonstrate Swarm's capabilities:

  1. Create the feature:

    npm run swarm feature user-management --description "User management feature"

  2. Add a dashboard route:

    npm run swarm route dashboard --feature user-management --path /dashboard --auth

  3. Create user CRUD operations:

    npm run swarm crud users --feature user-management --dataType User

  4. Add an API endpoint:

    npm run swarm api getUserStats --feature user-management --method GET --route /api/user-stats --auth

  5. Create a background job:

    npm run swarm job sendWelcomeEmail --feature user-management --cron "0 9 * * *" --entities User

  6. Add a query operation:

    npm run swarm operation getUserProfile --feature user-management --type query --entities User --auth

This creates a complete feature with:

  • Dashboard page with authentication
  • Full CRUD operations for users
  • API endpoint for user statistics
  • Background job for welcome emails
  • Query for user profiles

Available Generators

All Swarm Wasp generators are available:

  • feature - Create feature directories and structure
  • api - Generate API endpoints with optional middleware
  • crud - Create complete CRUD operations for entities
  • route - Generate routes and pages with authentication
  • job - Create background jobs with cron scheduling
  • operation - Generate queries and actions
  • api-namespace - Create API namespaces with middleware
  • config - Generate Wasp configuration files

For detailed generator documentation, see the Swarm Wasp Plugin README.

AI-Assisted Development

The template includes full MCP (Model Context Protocol) integration for AI-assisted development.

Setup

  1. Start the MCP server:

    npm run swarm:mcp

  2. Configure your AI tool (see MCP Setup Guide)

  3. Use AI prompts like:

    "Create a task management feature with a dashboard, task CRUD operations, and a daily reminder job"

    "Generate an API endpoint for getting user tasks with authentication required"

    "Add a new route for the settings page that requires authentication"

Type-Safe Wasp Configuration

The template uses the native Wasp Spec (@wasp.sh/spec). main.wasp.ts lives at the project root and pulls in a generated features barrel, so you never have to wire each feature into it by hand:

import { app } from "@wasp.sh/spec";
import Layout from "./src/shared/client/components/Layout" with { type: "ref" };
import { featureSpecs } from "./src/features/index.wasp";

export default app({
  name: "swarm_wasp_starter",
  title: "Swarm Wasp Starter",
  wasp: { version: "^0.24.0" },
  head: [
    '<meta name="description" content="Swarm Wasp Starter description" />',
    '<meta name="viewport" content="width=device-width, initial-scale=1.0" />',
    '<meta charSet="UTF-8" />',
  ],
  client: { rootComponent: Layout },
  spec: [featureSpecs],
});

Feature declarations

Each feature directory holds a feature.wasp.ts that exports a native spec array. Swarm's generators produce these declarations (and their with { type: "ref" } imports) for you:

import { type Spec, api, crud, job, route, page } from "@wasp.sh/spec";
import { Dashboard } from "./client/pages/Dashboard" with { type: "ref" };
import { getStats } from "./server/apis/getStats" with { type: "ref" };
import { sendReport } from "./server/jobs/sendReport" with { type: "ref" };

export const spec: Spec = [
  // Route definitions
  route("dashboard", "/dashboard", page(Dashboard, { authRequired: true })),
  // Api definitions
  api("GET", "/api/stats", getStats, { auth: true }),
  // Crud definitions
  crud("Users", "User", { getAll: {}, create: {} }),
  // Job definitions
  job(sendReport, {
    executor: "PgBoss",
    entities: ["User", "Task"],
    schedule: { cron: "0 9 * * 1" }, // Every Monday at 9 AM
  }),
];

Package Scripts

The template includes comprehensive npm scripts for Wasp development:

Development Scripts

  • dev, start - Start the Wasp development server
  • start:wasp - Start Wasp with TypeScript setup
  • start:db - Start the database only

Reset Scripts

  • reset, rs - Reset Wasp (clean + ts-setup)
  • reset:wasp, rsw - Full Wasp reset without starting
  • reset:db, rsd - Reset and migrate database
  • reset:all, rta - Reset both Wasp and database

Rebuild Scripts

  • rebuild, rb - Rebuild Wasp project
  • rebuild:wasp, rbw - Clean and rebuild Wasp
  • rebuild:db, rbd - Reset database migrations
  • rebuild:all, rba - Rebuild everything

Restart Scripts

  • restart, rt - Restart Wasp development server
  • restart:wasp, rtw - Restart Wasp with reset
  • restart:db, rtd - Restart database

Swarm Scripts

  • swarm - Run Swarm CLI commands
  • swarm:mcp - Start Swarm MCP server

Code Quality Scripts

  • lint - Run ESLint
  • lint:fix - Fix ESLint issues automatically
  • format - Format code with Prettier
  • format:check - Check Prettier formatting
  • typecheck - Run TypeScript type checking
  • validate - Run all quality checks

Utility Scripts

  • add-ui - Add shadcn/ui components

Customisation

Adding shadcn/ui Components

The template includes a script for adding shadcn/ui components:

npm run add-ui

This will prompt you to select components to add to your project.

Custom Templates

Override Swarm generator templates by placing custom versions in:

.swarm/templates/wasp/
├── api/
│   └── api.eta
├── crud/
│   └── crud.eta
└── route/
    └── page.eta

Configuration

Customise Swarm generators via swarm.config.json:

{
  "plugins": {
    "@ingenyus/swarm-wasp": {
      "plugin": "wasp",
      "enabled": true,
      "generators": {
        "api": { "enabled": true },
        "crud": { "enabled": true },
        "route": { "enabled": true }
      }
    }
  }
}

Next Steps

  1. Explore the generators - Try different Swarm generators to understand their capabilities
  2. Set up MCP - Configure AI tool integration for enhanced development
  3. Customise the template - Add your own components and styling
  4. Create your features - Build your application using the feature-based structure
  5. Deploy - Use Wasp's deployment features to host your application

Resources

License

MIT