Welcome to Swarm

This monorepo hosts Swarm, a Typescript code generation framework along with related plugins and starter templates.

Table of Contents

• Repository Structure
• Getting Started
• Scripts & Tooling
• Contributing
• License

Repository Structure

This repository is organised as a monorepo, using pnpm. Key directories include:

• apps/
  • swarm-wasp-starter: Minimal Wasp starter template
• packages/
  • swarm: Core framework including CLI, MCP server, plugin system, and app generator
  • swarm-wasp: Wasp component generators, templates, and enhanced configuration

Getting Started

Install pnpm if you don't have it already:

npm install -g pnpm

Clone, install and validate the project:

# Clone the repository
git clone <repository-url>
cd swarm

# Install dependencies
pnpm install

# Build, test, lint and format all packages
pnpm validate

To integrate Swarm components into your own projects or to extend the framework, see the relevant README files inside specific templates and packages (e.g. apps/swarm-wasp-starter, projects/swarm-wasp, etc.)

Scripts & Tooling

• Monorepo management: pnpm (pnpm-workspace.yaml)
• Code style and linting: ESLint, Prettier, EditorConfig
• Schema management: Zod
• Testing: Vitest
• CI/CD: GitHub Actions

Contributing

This project uses changesets with automatic generation via conventional commits for version management and releases.

Making Changes

1. Make your changes to the relevant package(s)
2. Commit using conventional commit format:

   git commit -m "feat: add new feature"
   git commit -m "fix(swarm): resolve issue in swarm"
   git commit -m "feat(swarm-wasp): add new command"
   git commit -m "feat!: breaking change"

3. Changesets are automatically generated from your commit messages during CI

Alternatively, you can still create changesets manually:

pnpm changeset

Release Process

Releases are automated through GitHub Actions:

1. When PRs are merged to main, a "Version Packages" PR is automatically created
2. The version PR is reviewed and merged to publish the packages to npm

Development Guidelines

• Follow the guidelines in CONTRIBUTING.md
• Use TypeScript best practices
• Add tests for new functionality
• Update documentation for new features
• Ensure all existing tests continue to pass

License

MIT License - see the LICENSE file for details.