Contributing to SonicJS

This guide is for developers who want to contribute to the SonicJS platform itself. If you're building an application with SonicJS, see the Installation guide instead.

Before You Start

We appreciate every developer who wants to contribute to SonicJS. To ensure the best experience for both contributors and maintainers, we've established a clear process for getting involved.

💡

Important: Start with Code, Not Meetings

We receive many requests from developers interested in contributing. While we value every potential contributor, we've found that the most effective way to get involved is to demonstrate your commitment through contributions first. Please submit at least one meaningful pull request before requesting a meeting or deeper integration into the project.

What Counts as a Meaningful Contribution?

• 🐛 Bug Fixes: Fix a bug from the issue tracker with a well-tested solution
• ✨ New Features: Implement a feature that has been discussed and approved
• 📝 Documentation: Significantly improve or add documentation
• 🧪 Test Coverage: Add meaningful tests for untested functionality
• 🎬 Video Content: Create tutorials, walkthroughs, or feature demos for YouTube

Create Video Content

We're looking for contributors to create video content for our YouTube channel. Video tutorials help developers learn SonicJS faster and reach a wider audience.

Video ideas:

• Getting started tutorials
• Feature walkthroughs and demos
• Building real-world projects with SonicJS
• Plugin development guides
• Tips and tricks

Reach out via GitHub Discussions if you're interested in creating video content.

Monorepo Setup

SonicJS uses a monorepo structure managed by npm workspaces. This allows us to develop the core framework, CLI tools, and documentation in a single repository.

Clone the Repository

# Fork the repository on GitHub first
# Then clone your fork:
git clone https://github.com/YOUR_USERNAME/sonicjs.git
cd sonicjs

# Add upstream remote
git remote add upstream https://github.com/lane711/sonicjs.git

# Install all dependencies (installs for all workspaces)
npm install

Start Development Server

# Start the development application
npm run dev

# Or start the documentation site
npm run dev:www

The development server runs at http://localhost:8787

Project Structure

The SonicJS monorepo is organized as follows:

sonicjs/
├── packages/
│   ├── core/                    # @sonicjs-cms/core - The main framework
│   │   ├── src/
│   │   │   ├── index.ts        # Package entry point
│   │   │   ├── middleware/     # Request middleware
│   │   │   ├── routes/         # HTTP route handlers
│   │   │   ├── services/       # Business logic
│   │   │   ├── templates/      # HTML templates
│   │   │   ├── plugins/        # Plugin system
│   │   │   │   ├── core/       # Plugin architecture
│   │   │   │   ├── core-plugins/  # Built-in plugins
│   │   │   │   └── available/  # Optional plugins
│   │   │   ├── collections/    # Collection definitions
│   │   │   └── types/          # TypeScript types
│   │   ├── migrations/         # Database migrations
│   │   └── package.json
│   │
│   └── create-app/             # create-sonicjs CLI tool
│       ├── src/
│       │   └── cli.js          # CLI entry point
│       ├── templates/
│       │   └── starter/        # Starter project template
│       └── package.json
│
├── www/                        # Documentation website (Next.js)
│   ├── src/
│   │   └── app/               # MDX documentation pages
│   └── package.json
│
├── my-sonicjs-app/            # Development/test application
│   ├── src/
│   │   └── index.ts           # App entry point
│   ├── wrangler.toml          # Cloudflare config
│   └── package.json
│
├── tests/                      # E2E tests
│   ├── e2e/                   # Playwright tests
│   └── playwright.config.ts
│
├── docs/                       # Internal documentation
├── package.json               # Root package.json (workspaces)
└── README.md

Key Directories

Available Scripts

Root Level Scripts

Run these from the repository root:

Database Scripts

Testing Scripts

Plugin Scripts

Contribution Process

Step 1: Find Something to Work On

Browse our GitHub Issues to find something to work on:

[ 🏷️

Good First Issues

Issues tagged for newcomers - great starting point

](https://github.com/lane711/sonicjs/labels/good%20first%20issue)

[ 🙋

Help Wanted

Issues where we actively need community help

](https://github.com/lane711/sonicjs/labels/help%20wanted)

[ 🔍

All Issues

Browse all open issues and find one that interests you

](https://github.com/lane711/sonicjs/issues)

[ 📚

Documentation

Help improve our docs - great for learning the project

](https://github.com/lane711/sonicjs/labels/documentation)

Step 2: Create a Feature Branch

# Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main

# Create a feature branch
git checkout -b feature/your-feature-name

Step 3: Make Your Changes

1. Make your changes in the appropriate package
2. Write tests for new functionality
3. Run tests to ensure everything passes
4. Update documentation if needed

Have questions? Ask in our Discord server - we're happy to help!

Step 4: Submit Your Pull Request

# Commit your changes
git add .
git commit -m "feat: add your feature description"

# Push to your fork
git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Step 5: After Your First PR is Merged

🎉

Congratulations!

After your first meaningful contribution is merged, you'll be:

Code Standards

General Guidelines

• TypeScript: All code must be in TypeScript with proper types
• Testing: New features must include tests
• Documentation: Public APIs must be documented
• Formatting: Use Prettier (runs automatically on commit)
• Linting: ESLint rules must pass

Commit Messages

We use conventional commit messages. Reference issue numbers when applicable.

feat: add new caching strategy
fix: resolve authentication bug (#123)
docs: update installation guide
test: add tests for plugin loader

Pull Request Checklist

Before submitting a PR, ensure:

• All tests pass (npm test)
• E2E tests pass (npm run test:e2e)
• Code is formatted (npm run format)
• Linting passes (npm run lint)
• Changes are documented if needed
• PR description explains the changes
• Related issue is referenced

Troubleshooting

Common Issues

Database Connection Errors

Error: Error: no such table: users

Solution:

# Run migrations
npm run db:migrate

# Verify migration status
wrangler d1 migrations list DB --local

Port Already in Use

Error: Error: listen EADDRINUSE: address already in use :::8787

Solution:

# Find and kill the process using port 8787
lsof -ti:8787 | xargs kill -9

Module Not Found / Import Errors

Error: Cannot find module 'hono'

Solution:

# Clear and reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Clear TypeScript build cache
rm -rf .wrangler

Build Failures

Error: Build fails when running npm run build:core

Solution:

1. Ensure you're using Node.js 18+
2. Clear build artifacts: rm -rf packages/core/dist
3. Reinstall dependencies: npm install
4. Try building again: npm run build:core

Getting Help

Resources:

• 📚 Full Documentation
• 🐛 GitHub Issues
• 💬 Discord

Ready to Contribute?

Find an Issue to Work On View Repository

Join the Community

Questions?

If you have questions about contributing:

1. Check existing issues - your question may already be answered
2. Ask in Discord - for general questions
3. Comment on the issue - for specific issue clarifications

We look forward to your contributions!