Contributing

StackKit is open source and contributions are very welcome. Whether you're fixing a typo, reporting a bug, or adding a new module — every contribution matters.

Ways to contribute

• Report a bug — Something broken? Open a bug report with steps to reproduce.
• Suggest a feature — Have an idea for a new module or improvement? Open a feature request.
• Improve the docs — Found a confusing explanation or a missing example? Send a PR.
• Fix a bug — Browse open issues and pick one to work on.
• Add a module — Implement a new integration (e.g., a different auth provider or storage service).

Development setup

git clone https://github.com/tariqul420/stackkit.git
cd stackkit

pnpm install

pnpm build

cd apps/stackkit
node bin/stackkit.js create test-app

Project structure

Understanding the repo layout will help you find where to make changes:

stackkit/
├── apps/
│   ├── stackkit/          # The CLI package (published to npm)
│   │   ├── src/           # TypeScript source
│   │   │   ├── cli/       # Command implementations (create, add, doctor, list)
│   │   │   ├── lib/       # Shared utilities (discovery, generation, prompts)
│   │   │   └── types/     # TypeScript type definitions
│   │   └── bin/           # CLI entry point
│   └── docs/              # This documentation site (Next.js + Fumadocs)
├── modules/               # Module definitions
│   ├── auth/              # Authentication modules
│   │   └── better-auth/   # Better Auth files and generator config
│   ├── database/          # Database modules
│   │   ├── prisma/        # Prisma files and generator config
│   │   └── mongoose/      # Mongoose files and generator config
│   ├── storage/           # Storage modules
│   ├── ui/                # UI modules
│   └── components/        # Pre-built UI components
└── templates/             # Base project templates
    ├── nextjs/            # Next.js template
    ├── express/           # Express template
    └── react/             # React + Vite template

Adding a new module

Each module in the modules/ directory follows the same structure:

modules/<category>/<module-name>/
├── module.json       # Module metadata (name, description, frameworks, etc.)
├── generator.json    # File operations and conditions
└── files/            # Files to copy into the project

The generator.json file is declarative — it describes what files to copy, what conditions apply, and what packages to install. You don't need to modify CLI source code to add most modules.

Adding a new template

Templates live in templates/<framework>/. A template is just a complete project structure for that framework. The CLI copies it as-is, then applies any selected modules on top.

When adding a template, make sure it:

• Uses TypeScript with strict mode
• Includes ESLint configuration
• Has a .env.example file
• Has a helpful README.md
• Follows the framework's official conventions

Code style

The codebase uses TypeScript and ESLint. Before submitting a PR, make sure your changes pass the linter:

pnpm lint

Submitting a pull request

1. Create a branch from main with a descriptive name (e.g., feat/add-drizzle-module or fix/mongoose-connection)
2. Make your changes
3. Test locally with node bin/stackkit.js
4. Submit the PR against main with a clear description of what changed and why

Questions?

Join the Discord server or open a GitHub Discussion — we're happy to help.

Testing

Running Tests

# Run all tests
pnpm test

# Test specific CLI commands
pnpm run test:create
pnpm run test:add
pnpm run test:doctor

# Test documentation build
cd apps/docs && pnpm run types:check

Manual Testing

1. Test CLI Commands

   # Build and test locally
   pnpm build
   node apps/stackkit/bin/stackkit.js --help

2. Test Project Generation

   # Create a test project
   mkdir test-project && cd test-project
   npx ../apps/stackkit/bin/stackkit.js create test-app --yes

3. Test Module Addition

   cd test-project
   npx ../apps/stackkit/bin/stackkit.js add --dry-run

Code Quality

TypeScript

• Use strict TypeScript settings
• Add proper type annotations
• Avoid any types

Code Style

• Follow existing patterns in the codebase
• Use meaningful variable and function names
• Add JSDoc comments for public APIs

Error Handling

• Use proper error messages
• Handle edge cases gracefully
• Provide helpful debugging information

Documentation

• Update docs for any new features
• Add code examples where helpful
• Keep API documentation up to date

License

By contributing to StackKit, you agree that your contributions will be licensed under the MIT License.