Contributing

helpbase is open source and welcomes contributions. This guide covers the monorepo structure, development workflow, and testing.

Repository structure

helpbase is a pnpm monorepo with Turborepo:

helpbase/
  apps/
    web/                   # The help center Next.js app
  packages/
    cli/                   # helpbase CLI (generate, audit, new, deploy)
    create-helpbase/       # npx create-helpbase scaffolder
    shared/                # Shared types, schemas, AI prompts
    ui/                    # shadcn/ui components + globals.css
  registry/
    helpbase/              # shadcn registry source (for `shadcn add`)
  scripts/
    sync-templates.mjs     # Syncs apps/web → scaffolder + registry
    smoke-install.sh       # End-to-end scaffolder smoke test

Note

The sync script is the most important piece of infrastructure. It ensures the scaffolder templates and shadcn registry always match the canonical apps/web/ implementation. CI fails if they drift.

Development setup

Clone the repo

git clone https://github.com/Codehagen/helpbase.git
cd helpbase

Install dependencies

pnpm install

Start the dev server

pnpm dev

Opens the help center at http://localhost:3000.

Testing

The test suite covers the CLI, scaffolder, content pipeline, and MDX components:

# Run all tests
pnpm test

# Run tests for a specific package
pnpm --filter cli test
pnpm --filter create-helpbase test
pnpm --filter web test

Smoke test

The install-path smoke test is the most important test. It scaffolds a real project, installs deps, runs the build, and verifies the output:

pnpm smoke:install

Warning

Every PR that changes apps/web/, packages/create-helpbase/, or scripts/sync-templates.mjs should run the smoke test before merging. This catches the class of bugs that unit tests miss: files that exist but don't constitute a buildable project.

Sync workflow

When you change files in apps/web/, the scaffolder templates and registry need updating:

Make your changes

Edit files in apps/web/ (components, content, lib, etc.)

Run the sync script

pnpm sync:templates

This copies your changes to both packages/create-helpbase/templates/ and registry/helpbase/.

Verify

pnpm test && pnpm smoke:install

What to contribute

Content

Improve documentation, fix typos, add examples.

Components

Add new MDX components or improve existing ones.

Create the component in apps/web/components/mdx/
Register it in apps/web/lib/mdx-components.tsx
Add a reference page in apps/web/content/reference/
Update the AI prompt in packages/shared/src/ai-text.ts to use it
Run pnpm sync:templates to update scaffolder + registry

Create the command in packages/cli/src/commands/
Register it in packages/cli/src/index.ts
Add tests in packages/cli/test/
Document it in content/cli/commands.mdx