DEV Community: Gary McPherson

Introduction to Swarm: Creating Custom Plugins

Gary McPherson — Wed, 19 Nov 2025 05:50:30 +0000

Part 1: An Extensible Typescript Code Generation Framework
Part 2: Building Full-Stack Apps With Wasp
Part 3: Creating a NextJS Plugin

In Part 2, we explored how Swarm's Wasp plugin accelerates Wasp application development by generating context-aware boilerplate code. Now, let's dive deeper into Swarm's extensibility by building a plugin for Next.js from scratch. We'll create a route generator that supports Next.js's flexible routing system, including App Router, Pages Router, dynamic routes, and route groups.

Why Next.js?

Next.js offers powerful routing capabilities through its file-based routing system, but creating routes manually can be repetitive. Whether you're using the App Router (app directory) or Pages Router (pages directory), you often find yourself creating similar file structures, component boilerplate, and configuration patterns.

A Swarm plugin can automate this process while respecting Next.js conventions and supporting the framework's various routing patterns:

Static and dynamic routes ([slug], [...slug], [[...slug]])
Route groups for organization ((group))
Private folders (_folder)
Special files (page.tsx, layout.tsx, loading.tsx, error.tsx, route.ts)

Setting Up the Plugin Structure

Let's start by creating a new plugin package. We'll call it @ingenyus/swarm-nextjs:

packages/swarm-nextjs/
├── src/
│   ├── generators/
│   │   ├── base/
│   │   │   ├── nextjs-generator.base.ts
│   │   │   └── index.ts
│   │   └── route/
│   │       ├── route-generator.ts
│   │       ├── schema.ts
│   │       └── index.ts
│   ├── common/
│   │   ├── config.ts
│   │   ├── path-resolver.ts
│   │   └── index.ts
│   ├── plugin.ts
│   └── index.ts
├── package.json
└── tsconfig.json

First, we need to install Swarm as a dependency:

{
  "name": "@ingenyus/swarm-nextjs",
  "version": "0.1.0",
  "dependencies": {
    "@ingenyus/swarm": "^1.0.0",
    "zod": "^4.0.0"
  }
}

Configuration System

One of the key features of the Next.js plugin is its flexible configuration system that allows developers to define custom directory structures using token-based path templates. This means you can customize how files are organized without modifying the plugin code.

Path Template Tokens

The plugin supports the following tokens in path templates:

{router}: 'app' or 'pages'
{src}: 'src/' if useSrcFolder is true, '' otherwise
{route}: Full route path including route groups (e.g., "(marketing)/blog/[slug]")
{routeClean}: Route path without route groups (e.g., "blog/[slug]")
{componentType}: Directory name for component type (components, lib, hooks, utils)
{fileName}: The generated file name (e.g., "page.tsx", "PostCard.tsx")

Default Configuration

The plugin provides sensible defaults that follow Next.js best practices. By default, it uses a "feature-based" structure where components are colocated with their routes:

// src/common/config.ts
export const DEFAULT_PATH_TEMPLATES: Required<NextJSPathTemplate> = {
  route: '{src}{router}/{routeClean}/{fileName}',
  component: '{src}{router}/{routeClean}/{componentType}/{fileName}',
  lib: '{src}{router}/{routeClean}/{componentType}/{fileName}',
  hook: '{src}{router}/{routeClean}/{componentType}/{fileName}',
  util: '{src}{router}/{routeClean}/{componentType}/{fileName}',
  serverAction: '{src}{router}/{routeClean}/actions/{fileName}',
  apiRoute: '{src}{router}/{routeClean}/route.ts',
};

This means a route at blog/[slug] would generate files at:

Route: app/blog/[slug]/page.tsx
Components: app/blog/[slug]/components/PostCard.tsx
Utils: app/blog/[slug]/lib/utils.ts

Defining the Route Generator Schema

The schema defines what parameters our generator accepts and how they're validated. For Next.js routes, we need to support multiple routing patterns and directory structures.

Let's create src/generators/route/schema.ts:

import { registerSchemaMetadata } from '@ingenyus/swarm';
import { z } from 'zod/v4';

// Route type determines which Next.js file convention to use
const routeTypeEnum = z.enum([
  'page',      // app/[path]/page.tsx or pages/[path].tsx
  'layout',    // app/[path]/layout.tsx
  'loading',   // app/[path]/loading.tsx
  'error',     // app/[path]/error.tsx
  'not-found', // app/not-found.tsx
  'route',     // app/api/[path]/route.ts (API route handler)
]);

// Router type determines which directory structure to use
const routerTypeEnum = z.enum(['app', 'pages']);

const baseSchema = z.object({
  // Route path (e.g., "blog/[slug]", "shop/[...slug]", "(marketing)/about")
  path: z
    .string()
    .min(1, 'Route path is required')
    .describe('The route path following Next.js conventions'),

  // Route type determines the file convention
  type: routeTypeEnum.default('page'),

  // Router type: App Router (app/) or Pages Router (pages/)
  router: routerTypeEnum.default('app'),

  // Component name (optional, derived from path if not provided)
  name: z.string().optional(),

  // Whether this is a client component (App Router only)
  client: z.boolean().default(false),

  // Whether to generate metadata export
  metadata: z.boolean().default(false),

  // Force overwrite existing files
  force: z.boolean().default(false),
});

export const schema = registerSchemaMetadata(baseSchema, {
  fields: {
    path: {
      type: 'string',
      required: true,
      description: 'The route path following Next.js conventions',
      shortName: 'p',
      examples: [
        'blog/[slug]',
        'shop/[...slug]',
        '(marketing)/about',
        'api/users/route',
      ],
      helpText: 'Supports dynamic segments ([slug]), catch-all ([...slug]), optional catch-all ([[...slug]]), route groups ((group)), and private folders (_folder)',
    },
    type: {
      type: 'enum',
      required: false,
      description: 'The type of route file to generate',
      shortName: 't',
      examples: ['page', 'layout', 'loading', 'error', 'route'],
      enumValues: ['page', 'layout', 'loading', 'error', 'not-found', 'route'],
      helpText: 'Determines which Next.js file convention to use',
    },
    router: {
      type: 'enum',
      required: false,
      description: 'Which router to use: App Router (app/) or Pages Router (pages/)',
      shortName: 'r',
      examples: ['app', 'pages'],
      enumValues: ['app', 'pages'],
      helpText: 'App Router supports more features (layouts, loading states, etc.)',
    },
    name: {
      type: 'string',
      required: false,
      description: 'Component name (auto-derived from path if not provided)',
      shortName: 'n',
      examples: ['BlogPost', 'UserProfile'],
    },
    client: {
      type: 'boolean',
      required: false,
      description: 'Generate as a client component (App Router only)',
      shortName: 'c',
      helpText: 'Adds "use client" directive at the top of the file',
    },
    metadata: {
      type: 'boolean',
      required: false,
      description: 'Generate metadata export',
      shortName: 'm',
      helpText: 'Adds a metadata export for SEO',
    },
    force: {
      type: 'boolean',
      required: false,
      description: 'Force overwrite existing files',
      shortName: 'f',
    },
  },
});

This schema supports:

Dynamic routes: blog/[slug], shop/[...slug], docs/[[...slug]]
Route groups: (marketing)/about, (shop)/cart
Private folders: _components/Button (not routable)
API routes: api/users/route (with type: 'route')
Special files: layouts, loading states, error boundaries

Base Generator Class

Before implementing the route generator, we need a base class that handles configuration loading and path resolution. This allows all Next.js generators to share common functionality.

// src/generators/base/nextjs-generator.base.ts
import {
  GeneratorBase,
  GeneratorServices,
  StandardSchemaV1,
  getConfigManager,
  Config,
} from '@ingenyus/swarm';
import {
  NextJSPluginConfig,
  DEFAULT_NEXTJS_CONFIG,
  PRESET_TEMPLATES,
} from '../../common/config';
import { PathResolver } from '../../common/path-resolver';

export abstract class NextJSGeneratorBase<S extends StandardSchemaV1>
  extends GeneratorBase<S>
{
  protected readonly pluginName = 'nextjs';
  private configCache: RequiredNextJSConfig | null = null;
  private pathResolver: PathResolver | null = null;

  constructor(services: GeneratorServices) {
    super(services);
  }

  /**
   * Get the Next.js plugin configuration
   * Loads config from swarm.config.json, merges with defaults, and handles preset structures
   */
  protected async getPluginConfig(): Promise<RequiredNextJSConfig> {
    // ...loads and caches configuration
  }

  /**
   * Get the path resolver instance
   */
  protected async getPathResolver(): Promise<PathResolver> {
    // ...returns cached PathResolver
  }

  /**
   * Resolve route file path using configured template
   */
  protected async resolveRoutePath(
    routePath: string,
    fileName: string,
    router?: 'app' | 'pages'
  ): Promise<string> {
    // ...uses PathResolver to resolve route paths
  }

  /**
   * Resolve component file path
   */
  protected async resolveComponentPath(
    routePath: string,
    componentType: 'components' | 'lib' | 'hooks' | 'utils',
    fileName: string,
    router?: 'app' | 'pages'
  ): Promise<string> {
    // ...uses PathResolver to resolve component paths
  }

  /**
   * Resolve server action file path
   */
  protected async resolveServerActionPath(
    routePath: string,
    fileName: string,
    router?: 'app' | 'pages'
  ): Promise<string> {
    // ...uses PathResolver to resolve server action paths
  }

  /**
   * Resolve API route file path
   */
  protected async resolveApiRoutePath(
    routePath: string,
    router?: 'app' | 'pages'
  ): Promise<string> {
    // ...uses PathResolver to resolve API route paths
  }
}

Implementing the Route Generator

Now let's implement the route generator that extends our base class. The core generate() method orchestrates the route generation process:

// src/generators/route/route-generator.ts
import {
  GeneratorServices,
  Out,
  toPascalCase,
  formatDisplayName,
} from '@ingenyus/swarm';
import { NextJSGeneratorBase } from '../base';
import { schema } from './schema';

export class RouteGenerator extends NextJSGeneratorBase<typeof schema> {
  name = 'route';
  description = 'Generates a Next.js route (page, layout, API route, etc.)';
  schema = schema;

  constructor(services: GeneratorServices) {
    super(services);
  }

  async generate(args: Out<typeof schema>): Promise<void> {
    const {
      path: routePath,
      type,
      router,
      name,
      client,
      metadata,
      force,
    } = args;

    const config = await this.getPluginConfig();
    const routerType = router ?? config.defaultRouter;

    // Parse the route path to handle dynamic segments, route groups, etc.
    const { componentName, params } = this.parseRoutePath(
      routePath,
      type,
      name
    );

    // Determine the file name based on route type
    const fileName = this.getFileName(type, routerType);

    // Resolve the target file path using the configured template
    const targetFile = await this.resolveRoutePath(
      routePath,
      fileName,
      routerType
    );

    // Ensure directory exists
    const dirPath = this.path.dirname(targetFile);
    if (!this.fileSystem.existsSync(dirPath)) {
      this.fileSystem.mkdirSync(dirPath, { recursive: true });
    }

    // Generate component code
    const componentCode = await this.generateComponentCode({
      componentName,
      type,
      router: routerType,
      client,
      metadata,
      params: params.map((p) => p.name),
      paramDetails: params,
    });

    // Write file
    const exists = this.fileSystem.existsSync(targetFile);
    if (exists && !force) {
      this.logger.warn(
        `File ${targetFile} already exists. Use --force to overwrite.`
      );
      return;
    }

    this.fileSystem.writeFileSync(targetFile, componentCode);
    this.logger.success(`Generated ${type} route: ${targetFile}`);
  }

  /**
   * Parse route path to extract component name and params
   * Handles dynamic segments ([slug]), catch-all ([...slug]), and route groups ((group))
   */
  private parseRoutePath(
    routePath: string,
    type: string,
    customName?: string
  ): {
    componentName: string;
    params: Array<{ name: string; isCatchAll: boolean }>;
  } {
    // ...extracts params and derives component name
  }

  /**
   * Derive component name from route path
   * Removes brackets, catch-all prefix, and route groups
   */
  private deriveComponentName(filePath: string, type: string): string {
    // ...cleans path and converts to PascalCase
  }

  /**
   * Get the file name based on route type and router
   */
  private getFileName(type: string, router: string): string {
    // ...maps route types to Next.js file conventions
  }

  /**
   * Generate component code based on route type
   */
  private async generateComponentCode(options: {
    componentName: string;
    type: string;
    router: string;
    client: boolean;
    metadata: boolean;
    params: string[];
    paramDetails: Array<{ name: string; isCatchAll: boolean }>;
  }): Promise<string> {
    // ...generates React component or API route handler code
  }

  /**
   * Generate props interface for dynamic routes
   */
  private generatePropsInterface(
    componentName: string,
    paramDetails: Array<{ name: string; isCatchAll: boolean }>,
    type: string
  ): string {
    // ...generates TypeScript interface for component props
  }

  /**
   * Get component props signature
   */
  private getComponentProps(
    componentName: string,
    type: string,
    paramDetails: Array<{ name: string; isCatchAll: boolean }>
  ): string {
    // ...generates props destructuring signature
  }

  /**
   * Generate component body based on type
   */
  private generateComponentBody(componentName: string, type: string): string {
    // ...generates JSX body for different route types
  }

  /**
   * Generate API route handler
   */
  private generateRouteHandler(handlerName: string, params: string[]): string {
    // ...generates Next.js API route handler
  }

  /**
   * Generate metadata export for SEO
   */
  private generateMetadataExport(componentName: string): string {
    // ...generates Next.js metadata export
  }
}

For the complete implementation including all method bodies, see the full source code on GitHub Gist.

The generate() method follows a clear flow:

Load configuration - Gets plugin config and determines router type
Parse route path - Extracts component name and dynamic params
Resolve file path - Uses configured path template to determine target location
Generate code - Creates the component/route handler code
Write file - Writes to disk with force flag handling

Key supporting methods handle:

parseRoutePath() - Extracts dynamic segments and derives component names, properly handling catch-all routes ([...slug]) vs regular dynamic routes ([slug])
deriveComponentName() - Cleans route paths to create valid TypeScript identifiers
getFileName() - Maps route types to Next.js file conventions

For the complete implementation including all helper methods (generateComponentCode, generatePropsInterface, generateComponentBody, etc.), see the full source code.

Creating the Plugin

Now let's create the plugin file src/plugin.ts:

import { createPlugin } from '@ingenyus/swarm';
import { RouteGenerator } from './generators/route';

export const nextjs = createPlugin(
  'nextjs',
  RouteGenerator
);

And export it from src/index.ts:

export { nextjs } from './plugin';
export { RouteGenerator } from './generators/route';

Configuring the Plugin

The plugin can be configured in your swarm.config.json or package.json file. The configuration allows you to customize directory structures using path templates:

{
  "plugins": [
    {
      "import": "nextjs",
      "from": "@ingenyus/swarm-nextjs",
      "config": {
        "useSrcFolder": false,
        "defaultRouter": "app",
        "directories": {
          "components": "components",
          "lib": "lib",
          "hooks": "hooks",
          "utils": "utils",
          "actions": "actions"
        },
        "paths": {
          "route": "{src}{router}/{routeClean}/{fileName}",
          "component": "{src}{router}/{routeClean}/{componentType}/{fileName}"
        }
      }
    }
  ]
}

Custom Directory Structures

You can define custom structures by overriding path templates. For example, to use a shared-components structure:

{
  "plugins": [
    {
      "import": "nextjs",
      "from": "@ingenyus/swarm-nextjs",
      "config": {
        "paths": {
          "route": "{src}{router}/{routeClean}/{fileName}",
          "component": "{src}{router}/{componentType}/{fileName}",
          "lib": "{src}{router}/{componentType}/{fileName}"
        }
      }
    }
  ]
}

This would generate components in app/components/ instead of colocating them with routes.

Using the Generator

Now, you can set up Swarm's MCP integration to use your preferred assistant, or generate routes using the CLI:

# Generate a simple page
npm run swarm -- route --path blog

# Generate a dynamic route
npm run swarm -- route --path 'blog/[slug]'

# Generate a catch-all route
npm run swarm -- route --path 'shop/[...slug]'

# Generate a layout
npm run swarm -- route --path dashboard --type layout

# Generate an API route
npm run swarm -- route --path api/users --type route

# Use Pages Router
npm run swarm -- route --path contact --router pages

Example Outputs

Static Page (`app/blog/page.tsx`)

import React from 'react';

export default function Blog() {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-2xl font-bold mb-4">Blog</h1>
      {/* TODO: Add page content */}
    </div>
  );
}

Dynamic Route (`app/blog/[slug]/page.tsx`)

import React from 'react';

interface BlogPostProps {
  params: {
    slug: string;
  };
}

export default function BlogPost(props: BlogPostProps) {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-2xl font-bold mb-4">Blog Post</h1>
      {/* TODO: Add page content */}
    </div>
  );
}

Catch-All Route (`app/shop/[...slug]/page.tsx`)

import React from 'react';

interface SlugProps {
  params: {
    slug: string[];
  };
}

export default function Slug(props: SlugProps) {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-2xl font-bold mb-4">Slug</h1>
      {/* TODO: Add page content */}
    </div>
  );
}

Note that catch-all routes correctly generate string[] types for the params, and the component name is properly derived (removing the ... prefix and brackets).

API Route (`app/api/users/route.ts`)

import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  // TODO: Implement GET handler
  return NextResponse.json({ message: 'GET handler' });
}

export async function POST(request: NextRequest) {
  // TODO: Implement POST handler
  return NextResponse.json({ message: 'POST handler' });
}

Layout (`app/dashboard/layout.tsx`)

import React from 'react';

interface DashboardLayoutProps {
  children: React.ReactNode;
}

export default function DashboardLayout({ children }: DashboardLayoutProps) {
  return (
    <div>
      {/* TODO: Add layout content */}
      {children}
    </div>
  );
}

Loading State (`app/blog/loading.tsx`)

import React from 'react';

export default function BlogLoading() {
  return (
    <div className="flex items-center justify-center p-8">
      <div className="text-lg">Loading Blog...</div>
    </div>
  );
}

Error Boundary (`app/blog/error.tsx`)

import React from 'react';

interface BlogErrorProps {
  error: Error & { digest?: string };
  reset: () => void;
}

export default function BlogError({ error, reset }: BlogErrorProps) {
  return (
    <div className="flex flex-col items-center justify-center p-8">
      <h2 className="text-xl font-bold mb-4">Something went wrong!</h2>
      <p className="text-red-600 mb-4">{error.message}</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

Next Steps

This route generator demonstrates the core concepts of building a Swarm plugin, but there's much more we could add:

Component Generator: Generate reusable React components with props interfaces
Server Action Generator: Generate server actions for form handling
API Route Handler Generator: More sophisticated API route generation with validation
Layout Generator: Generate nested layouts with proper TypeScript types
Metadata Generator: Standalone metadata generation for SEO

Each generator would follow the same pattern: define a schema, implement the generator class, create templates, and register it with the plugin. The framework handles CLI command generation, MCP tool exposure and validation.

If you're building with Next.js and want to accelerate your development workflow, consider building your own Swarm plugin!

Introduction to Swarm: an extensible Typescript code generation framework

Gary McPherson — Mon, 17 Nov 2025 07:36:49 +0000

Part 1: An Extensible Typescript Code Generation Framework
Part 2: Building Full-Stack Apps With Wasp
Part 3: Creating Custom Plugins

As developers, we all reach a point when writing repetitive boilerplate stops being a minor annoyance and starts having a real impact on our productivity. You find yourself creating the same directory structure, writing the same configuration blocks, copying and pasting similar component patterns, then tweaking each instance slightly. What begins as a few minutes here and there quickly adds up to hours lost on manual scaffolding.

That's where this journey began for me. Initially, I built a collection of scripts to automate component creation for a side project. But the more I used those scripts, the more I realised this problem wasn't unique to my project or the framework I was using.

Today, Swarm is an extensible TypeScript code generation framework built on a plugin-based architecture. The first plugin I created solved my own needs for generating Wasp components, but the core library can be extended to generate code for any framework or platform.

So, dear developer, I'd like to share why Swarm exists, how it came to be and what it might offer you.

Why Wasp?

Before diving into Swarm itself, it's worth sharing the context that led to its creation. While researching framework options for a side project, I discovered Wasp, a full-stack web development framework, through their OpenSaaS starter template. I'd been looking at various paid SaaS starter templates at the time, but Wasp's offering stood out because it was free and included genuinely useful features out of the box.

I've been working with Wasp for almost a year now and in that time, I've become a contributor to the project and been fortunate enough to been recognised as a community expert. I believe the team behind it has built something with genuine potential. But as a relatively early (pre-1.0) project, I encountered certain friction points as I started using it more extensively.

The Challenges

Wasp gives developers considerable freedom in how they organise their projects. That flexibility can feel empowering, but it also imposes cognitive load as you have to decide on a structure yourself, often without clear guidance on what scales well. In my first project, I implemented a feature-based structure that segregated front- and back-end components into cohesive feature directories. Conceptually, I still stand by that decision, but there are definitely implementation details I'd approach differently now.

The configuration file presents another issue. Wasp uses a single configuration file, defined in their own DSL or TypeScript, to declare all server-side components. That includes RPC-style queries, actions (mutations), CRUD operations, background jobs, HTTP API endpoints, and page routes. The file offers a shallow learning curve and it's initially easy to manage, but it's monolithic and defines every component for the application. For complex app, it can grow very large and becomes increasingly difficult to navigate, even with careful organisation.

Then there's the server-side code structure. Wasp tends to recommend organising server operations in monolithic files like actions.ts or queries.ts. This works fine for small project, but as applications grow, these files can become unwieldy. More fundamentally, this pattern contrasts sharply with typical front-end conventions that define one component per file. That inconsistency creates mental overhead when switching between client and server code.

The Journey

Swarm started out as a set of simple scripts I created to automate component creation for my first Wasp project. They worked well enough and I figured other Wasp developers might find them useful, so I decided to package them as a CLI tool that could easily be installed in other projects.

The next realisation was that MCP (Model Context Protocol) support would make these tools easier to use within AI-assisted development workflows. To enable that, I needed to break the core functionality out, with separate CLI and MCP packages, which forced me to think more carefully about the overall architecture.

Once I had both CLI and MCP working, another insight followed: this problem wasn't Wasp-specific. The same pattern of generating type-safe, context-aware boilerplate could apply to any framework. So I refactored everything into a technology-agnostic core handling both CLI command and MCP tool generation, with a separate plugin defining Wasp-specific generators.

Another revelation arrived when it struck me that CLI commands and MCP tools could be generated entirely from Zod schemas. I was already using Zod in a limited capacity throughout the application, but I realised I could define the schema once and get CLI flags, MCP tool parameters and validation for free, making plugin development much simpler.

While ironing out some compatibility bugs between the Zod 4 dependency in Swarm and the Zod 3 dependency in Wasp, I learned about Standard Schema and implemented support for that spec instead, allowing plugin schemas to be built with any library of the author's choice.

State Of The Union

At the time of writing, the Swarm "ecosystem" consists of three main components:

Swarm Core

As previously mentioned, the core framework is built around a plugin-based architecture that supports user-defined generators for different types of content, e.g. APIs, components, configuration or whatever makes sense for your use case. Generators and plugins implement simple, lightweight interfaces and leverage Standard Schema schemas for input validation.

export interface Generator<S extends StandardSchemaV1 = StandardSchemaV1> {
  name: string;
  description: string;
  schema: S;
  generate: (args: Out<S>) => Promise<void>;
}

export interface Plugin {
  name: string;
  providers: Array<GeneratorProvider>;
}

Those schemas drive both the command-line and MCP interfaces. You define a generator with a schema, and Swarm automatically exposes it as a command-line option and as an MCP tool that AI assistants can use, with no separate configuration or manual wiring required.

Swarm also includes a templating system built on Eta, with support for custom template overrides. If you need to tweak the output of a generator, you can place a modified template in a known location and the generator will use it in favour of the built-in version.

The Swarm Wasp Plugin

The Wasp plugin provides generators for all documented Wasp components. That includes API Endpoints and Namespaces, CRUD operations, Actions, Queries, Page Routes, and Background Jobs. All output is type-safe and compatible with your defined Prisma entities.

Beyond code generation, the plugin addresses those issues I mentioned earlier:

It introduces an enhanced configuration system that supports feature-based feature.wasp.ts files alongside the main main.wasp.ts. This contrasts with the traditional monolithic style, creating smaller, more manageable files and ensuring feature configuration is self-contained.
It provides a fluent API through an extended App class that makes configuration files more concise and readable.
It enforces a consistent, feature-based directory structure with a component-per-file pattern that mirrors front-end conventions. In the spirit of Prettier, I wanted to just take away all the concerns with "how" and just be able to focus on the "what".

The Swarm Wasp Starter

The starter template demonstrates how to build Wasp applications using Swarm's code generation functionality. It provides a minimal implementation that's an ideal foundation for building custom starter templates on top of.

It includes modern tooling like Tailwind CSS 4 and shadcn/ui components, with several useful development scripts for common Wasp workflows. And of course, it includes Swarm's full MCP integration ready for AI-assisted development. If you're building a Wasp application and want to see how Swarm can accelerate your development workflow, give it a try!

What's Next?

This introduction covered the motivation, evolution, and current state of Swarm. In Part 2, I'll walk through creating a full-stack Wasp application using the Swarm toolkit. I'll show how the generators work in practice and how they can speed up development while maintaining type safety and consistency.

And if you're a Wasp developer dealing with some of the same friction points I encountered, I'd love to hear your thoughts.

Introduction to Swarm: Building full-stack apps with Wasp

Gary McPherson — Mon, 17 Nov 2025 07:34:35 +0000

Part 1: An Extensible Typescript Code Generation Framework
Part 2: Building Full-Stack Apps With Wasp
Part 3: Creating Custom Plugins

In Part 1, I shared the evolution of Swarm from a collection of project scripts into a full boilerplate generation framework. In this article, we'll walk through the steps of building a Wasp application using the Swarm Wasp Starter template, and I'll demonstrate how the generators work with real examples.

I'll be referencing the kitchen-sink example project from the Wasp repository throughout this article. It's a comprehensive example that features all major Wasp features, so it serves as a good reference point to understand how Swarm works.

Key Differences

Swarm implements a couple of notable changes to standard Wasp projects that it's useful to be aware of.

Directory Structure

Wasp allows you to organise projects however you like, which is appealing at face-value. But when you're starting and scaling projects, that freedom comes with the cost of cognitive burden attached as you have to determine the best way to organise your files and directories.

Taking inspiration from Prettier, the Wasp plugin aims to remove all the mental effort of deciding how project files should be organised by enforcing a convention-driven, feature-based directory structure. Each feature directory is self-contained, with client and server subdirectories organised in a consistent structure, and a feature.wasp.ts configuration file that lives alongside the components it defines.

Here's what a typical feature directory looks like:

src/features/operations/
├── feature.wasp.ts
├── client/
│   └── pages/
│       ├── Serialization.tsx
│       ├── TaskDetail.tsx
│       └── Tasks.tsx
└── server/
    ├── actions/
    │   ├── createTask.ts
    │   ├── deleteCompletedTasks.ts
    │   ├── toggleAllTasks.ts
    │   └── updateTaskIsDone.ts
    └── queries/
        ├── getNumTasks.ts
        ├── getTask.ts
        └── getTasks.ts

This is in contrast to the standard guidance that recommends a single actions.ts file containing multiple actions, or a queries.ts file containing multiple queries. As the project grows, those files become harder to navigate and may ultimately get split up into sub-files, which again has an associated cost to plan and implement. The Wasp plugin's conventions dictate that each component lives in its own file, which also harmonises server-side components with client-side ones.

The main.wasp.ts file is still required, but it's much smaller as it purely handles application-level configuration like authentication and the root component. Feature-specific configuration now lives in feature.wasp.ts files, which keeps the main file manageable even as you add more features.

Configuration Syntax

Wasp's declarative configuration syntax works fine, but it can be verbose. Swarm's extended App class provides a fluent API that makes configuration more concise and readable.

For example, typical Wasp declarations look like this:

app.route("tasks", {
  path: "/tasks",
  to: app.page("tasks", {
    component: {
      importDefault: "Tasks",
      from: "@src/features/operations/client/pages/Tasks",
    },
  }),
});

app.crud("tasks", {
  entity: "Task",
  operations: {
    create: {
      overrideFn: {
        import: "create",
        from: "@src/features/crud/server/cruds/tasks" },
      },
    },
    getAll: {
      overrideFn: {
        import: "getAll",
        from: "@src/features/crud/server/cruds/tasks" },
      },
    },
  },
);

While the equivalent in Swarm looks like this:

app
  .addRoute("operations", "tasks", {
    path: "/tasks",
    auth: false
  })
  .addCrud("crud", "tasks", {
    entity: "Task",
    create: { override: true },
    getAll: { override: true }
  });

The fluent API lets generators chain these calls together, and Swarm organises them automatically so related declarations are grouped together and sorted alphabetically. It's a small detail, but it makes the configuration files much easier to read.

The generators automatically generate component files in consistent locations, following the plugin's structural conventions, so you don't have to define those yourself. The generated code is also fully type-safe, so if you reference an entity or property that doesn't exist in your Prisma schema, TypeScript will catch it.

Getting Started

The Swarm Wasp Starter template includes Swarm and the Wasp plugin, along with Tailwind CSS 4 and shadcn/ui components. You'll also find a collection of useful npm scripts for common Wasp workflows.

Run this command to create a new project using the starter:

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

This clones the starter template and populates any templated values. Once installation is complete, navigate into the project directory and set it up:

npm run reset

Using the CLI

The Swarm framework provides CLI commands for each of the generators defined by any active plugins, while the Wasp Starter template provides access to the CLI via the npm run swarm package script.

Let's say we want to replicate the kitchen-sink application, but built using Swarm.

Prisma Schema

The first step is to define any necessary entities in our schema.prisma file:

model User {
  id Int @id @default(autoincrement())

  isOnAfterSignupHookCalled        Boolean @default(false)
  isOnAfterLoginHookCalled         Boolean @default(false)
  isOnAfterEmailVerifiedHookCalled Boolean @default(false)

  tasks                 Task[]
  address               String?
  votes                 TaskVote[]
}

model Task {
  id          Int            @id @default(autoincrement())
  description String
  isDone      Boolean        @default(false)
  user        User           @relation(fields: [userId], references: [id])
  userId      Int
  votes       TaskVote[]
}

model TaskVote {
  id     String @id @default(cuid())
  user   User   @relation(fields: [userId], references: [id])
  userId Int
  task   Task   @relation(fields: [taskId], references: [id])
  taskId Int
}

Then we need to configure basic username authentication to enable auth settings:

main.wasp.ts

app.auth({
  userEntity: "User",
  methods: {
    usernameAndPassword: {},
  },
  // Required, but not used in this tutorial
  onAuthFailedRedirectTo: "/login",
});

Migrate the database and compile the project so Typescript is aware of the new entities:

wasp db migrate-dev --name init && wasp compile

Feature Directory

Before generating any Wasp components, we must first generate a feature directory to contain them:

npm run swarm -- feature --target operations

All Swarm command arguments also support a short form, which you can review by using the -h argument to display the command help. The shortened form of the previous command would be:

npm run swarm -- feature -t operations

Output

This creates the src/features/operations/ directory containing a bare feature.wasp.ts file, ready to start adding components.

feature.wasp.ts

import { App } from "@ingenyus/swarm-wasp";

export default function configureFeature(app: App, feature: string): void {
  app
}

Routes & Pages

Next, we need to generate a login page (in the pre-existing root feature) and we'll also create a route for viewing tasks:

npm run swarm -- route --feature root --path /login --name login
npm run swarm -- route --feature operations --name tasks --path /tasks --auth

Output

These commands generate page components at src/features/operations/client/pages/Tasks.tsx and src/features/root/client/pages/Login.tsx, then adds definitions to the respective feature.wasp.ts files. The --auth flag indicates the route requires authentication, which is reflected in the helper method call.

root/feature.wasp.ts

  app
    // Route definitions
    .addRoute(feature, "login", {
      path: "/login",
      auth: false,
    });

operations/feature.wasp.ts

  app
    // Route definitions
    .addRoute(feature, "tasks", {
      path: "/tasks",
      auth: true,
    });

Login.tsx

import React from "react";

export const Login = () => {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-2xl font-bold mb-4">Login</h1>
      {/* TODO: Add page content */}
    </div>
  );
};

Tasks.tsx

import React from "react";

export const Tasks = () => {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-2xl font-bold mb-4">Tasks</h1>
      {/* TODO: Add page content */}
    </div>
  );
};

Operations

Next, we can generate queries and actions for Task entity:

npm run swarm -- query --feature operations --operation getAll --data-type Task --name getTasks
npm run swarm -- action --feature operations --operation create --data-type Task --name createTask

Output

These commands create boilerplate for the query and action handlers in src/features/operations/server/queries/getTasks.ts and src/features/operations/server/actions/createTask.ts respectively. The output is properly typed based on your Prisma schema, so you get full type-safety out of the box.

feature.wasp.ts

  app
    // Action definitions
    .addAction(feature, "createTask", {
      entities: ["Task"],
      auth: false,
    })
    // Query definitions
    .addQuery(feature, "getTasks", {
      entities: ["Task"],
      auth: false,
    })

createTask.ts

import { Task } from "wasp/entities";
import { HttpError } from "wasp/server";
import type { CreateTask } from "wasp/server/operations";

export const createTask: CreateTask<Pick<Task, "description" | "userId"> & Partial<Pick<Task, "isDone">>> = async (data, context) => {
  try {
    const createdTask = await context.entities.Task.create({
      data: {
        ...data,
      }
    });

    return createdTask;
  } catch (error) {
    console.error("Failed to create Task:", error);

    throw new HttpError(500, `Failed to create Task${error instanceof Error ? `: ${error.message}` : ''}`);
  }
};

getTasks.ts

import { HttpError } from "wasp/server";
import type { GetAllTasks } from "wasp/server/operations";

export const getAllTasks = (async (_args, context) => {
  try {
    const tasks = await context.entities.Task.findMany();

    return tasks;
  } catch (error) {
    console.error("Failed to get all tasks:", error);

    if (error instanceof HttpError) {
      throw error;
    }

    throw new HttpError(500, `Failed to get all tasks${error instanceof Error ? `: ${error.message}` : ''}`);
  }
}) satisfies GetAllTasks<void>;

CRUD Operations

For CRUD operations, the kitchen-sink application offers a separate crud feature. Let's generate that and a set of operations:

npm run swarm -- feature --target crud
npm run swarm -- crud --feature crud --data-type Task --override get getAll create

Output

This configures all the standard CRUD operations, with function overrides for the get, getAll and create operations. CRUD operations are a special case, with all overridden functions being exported from src/features/crud/server/cruds/tasks.ts.

feature.wasp.ts

  app
    // Crud definitions
    .addCrud(feature, "tasks", {
      entity: "Task",
      get: {
        override: true
      },
      getAll: {
        override: true
      },
      create: {
        override: true
      },
      update: {},
      delete: {},
    });

tasks.ts

import { type Task } from "wasp/entities";
import { HttpError } from "wasp/server";
import { type Tasks } from "wasp/server/crud";

export const getTask = (async ({ id }, context) => {
  if (!context.user) {
    throw new HttpError(401);
  }

  try {
    const task = await context.entities.Task.findUnique({
      where: { id },
    });

    if (!task) {
      throw new HttpError(404, `task ${id} not found`);
    }

    return task;
  } catch (error) {
    console.error(`Failed to get task ${id}:`, error);

    if (error instanceof HttpError) {
      throw error;
    }

    throw new HttpError(500, `Failed to get task ${id}${error instanceof Error ? `: ${error.message}` : ''}`);
  }
}) satisfies Tasks.GetQuery<Pick<Task, "id">>;

export const getAllTasks = (async (_args, context) => {
  if (!context.user) {
    throw new HttpError(401);
  }

  try {
    const tasks = await context.entities.Task.findMany();

    return tasks;
  } catch (error) {
    console.error("Failed to get all tasks:", error);

    if (error instanceof HttpError) {
      throw error;
    }

    throw new HttpError(500, `Failed to get all tasks${error instanceof Error ? `: ${error.message}` : ''}`);
  }
}) satisfies Tasks.GetAllQuery<void>;

export const createTask: Tasks.CreateAction<Pick<Task, "description" | "userId"> & Partial<Pick<Task, "isDone">>> = async (data, context) => {
  if (!context.user) {
    throw new HttpError(401);
  }

  try {
    const createdTask = await context.entities.Task.create({
      data: {
        ...data,
      }
    });

    return createdTask;
  } catch (error) {
    console.error("Failed to create Task:", error);

    throw new HttpError(500, `Failed to create Task${error instanceof Error ? `: ${error.message}` : ''}`);
  }
};

HTTP API Endpoints

The kitchen-sink example includes various endpoints in the apis feature, so let's add one:

npm run swarm -- feature --target apis
npm run swarm -- api --feature apis --name fooBar --method ALL --path /foo/bar --entities Task

Output

This creates the endpoint handler in src/features/apis/server/apis/fooBar.ts and registers it in your feature configuration. The generator handles the middleware setup and entity access automatically.

feature.wasp.ts

  app
    // Api definitions
    .addApi(feature, "fooBar", {
      method: "ALL",
      route: "/foo/bar",
      entities: ["Task"],
      auth: false,
      customMiddleware: true,
    });

tasks.ts

import type { FooBar } from "wasp/server/api";

export const fooBar: FooBar = async (req, res, context) => {
  // TODO: Implement your API logic here
  res.json({ message: "OK" });
};

Running the app

While the app doesn't yet have any proper business logic, all the boilerplate is valid code and you should be able to confirm the application runs by executing:

npm run dev

After the application opens, navigate to http://localhost:3000/tasks and you should be redirected to the /login page. The page component hasn't been completed yet, but simply verifies that the application can be compiled and executed successfully.

AI-Assisted Development with MCP

The CLI works well when you know exactly what you want to generate. Sometimes it's faster to just describe your intent and let an AI assistant figure out the right commands. That's where MCP comes in.

Start the MCP server with:

npm run swarm:mcp

Once you've configured your AI tool (Cursor, Claude Code, or VS Code Copilot) to connect to the server, you can use natural language prompts. Instead of remembering the exact CLI syntax, you can say something like:

"Create an operations feature with a route to view tasks, queries and actions for the Task entity, and an authenticated API endpoint."

The AI understands your intent and calls the appropriate MCP tools, which map directly to the CLI commands. You get the same generated code, but without having to construct the command yourself.

This becomes really powerful when you're building out a feature incrementally. You might start with a basic structure, then ask the AI to add more components as you think of them. Each request generates the right files in the right places, and everything stays consistent because it's all going through the same generators.

The MCP integration means Swarm's generators are available to any AI tool that supports the protocol. You're not locked into a specific editor or assistant—if it can talk MCP, it can use Swarm.

Putting It All Together

I've created a comparison video that shows a traditional Wasp application side-by-side with one built using Swarm Wasp Starter. Both are based on the kitchen-sink example, so you can see how the same functionality looks in each approach.

The video demonstrates the complete applications, highlighting the differences in structure, configuration, and development workflow. If you're curious about how Swarm changes the day-to-day experience of building Wasp apps, this should give you a clear picture.

If you're building with Wasp, give the Swarm Wasp Starter a try!

DEV Community: Gary McPherson

Introduction to Swarm: Creating Custom Plugins

Why Next.js?

Setting Up the Plugin Structure

Configuration System

Path Template Tokens

Default Configuration

Defining the Route Generator Schema

Base Generator Class

Implementing the Route Generator

Creating the Plugin

Configuring the Plugin

Custom Directory Structures

Using the Generator

Example Outputs

Static Page (app/blog/page.tsx)

Dynamic Route (app/blog/[slug]/page.tsx)

Catch-All Route (app/shop/[...slug]/page.tsx)

API Route (app/api/users/route.ts)

Layout (app/dashboard/layout.tsx)

Loading State (app/blog/loading.tsx)

Error Boundary (app/blog/error.tsx)

Next Steps

Introduction to Swarm: an extensible Typescript code generation framework

Why Wasp?

The Challenges

The Journey

State Of The Union

Swarm Core

The Swarm Wasp Plugin

The Swarm Wasp Starter

What's Next?

Introduction to Swarm: Building full-stack apps with Wasp

Key Differences

Directory Structure

Configuration Syntax

Getting Started

Using the CLI

Prisma Schema

Feature Directory

Output

Routes & Pages

Output

Operations

Output

CRUD Operations

Output

HTTP API Endpoints

Output

Running the app

AI-Assisted Development with MCP

Putting It All Together

Static Page (`app/blog/page.tsx`)

Dynamic Route (`app/blog/[slug]/page.tsx`)

Catch-All Route (`app/shop/[...slug]/page.tsx`)

API Route (`app/api/users/route.ts`)

Layout (`app/dashboard/layout.tsx`)

Loading State (`app/blog/loading.tsx`)

Error Boundary (`app/blog/error.tsx`)