discourse-boilerplate

Scaffold a bare Discourse plugin or theme with one command. Designed to be simple, predictable, and opinionated about basic coding standards for JS, CSS, and Ruby.

Minimum Requirements

• Node >= 18.17.0
• macOS/Linux
• Optional for Ruby linting: a working Ruby toolchain (e.g., Xcode Command Line Tools on macOS) and Bundler

Features

• Create a Discourse plugin or theme via CLI
• Token substitution for name, slug, namespace, author, and version
• Preconfigured linting:
  • ESLint (Standard) for JS
  • Stylelint (Discourse) for CSS/SCSS
  • RuboCop for Ruby (plugin scaffold)
• Generated files end with a trailing newline to satisfy eol-last

Install

When published to npm:

• Global: npm install -g discourse-boilerplate then run discourse-boilerplate --help
• One‑off (recommended): npx discourse-boilerplate@latest --help

For local development in this repo:

• node bin/discourse-boilerplate.js --help

Quick Start

Create a plugin:

npx discourse-boilerplate -t plugin -n "My Plugin" -s my-plugin -ns MyPlugin -a "Your Name" -arl "https://example.com" -pv 0.1.0 -dv stable

Create a theme:

npx discourse-boilerplate -t theme -n "My Theme" -s my-theme -ns MyTheme -a "Your Name" -arl "https://example.com" -pv 0.1.0 -dv stable

Optional inclusions (examples):

# include GitHub workflow, exclude CircleCI, Docker, and Playwright
npx discourse-boilerplate -t plugin -n "My Plugin" -s my-plugin -ns MyPlugin -gwf true -cicd false -dkr false -pwt false

Parameters

• -t, --type <plugin|theme> project type (default: plugin)
• -n, --name <name> project name (required)
• -s, --slug <slug> project slug (required)
• -ns, --namespace <namespace> Ruby module namespace (required)
• -a, --author <author> project author (default: current OS user if omitted)
• -arl, --author_url <url> project author URL (default: empty)
• -pv, --project-version <semver> project version (default: 0.1.0)
• -dv, --discourse-version <tag> Discourse version tag for CI (default: stable)
• -rbv, --ruby-version <version> Ruby version used in Docker/CI (default: 3.3)
• -cicd, --circleci <boolean> include CircleCI config (default: true)
• -gwf, --gitworkflow <boolean> include GitHub workflow (default: true)
• -dkr, --docker <boolean> include Docker files (default: true)
• -pwt, --playwright <boolean> include Playwright setup (default: true)

Generated Structure

Plugin:

<slug>/
  plugin.rb
  assets/
    javascripts/discourse/initializers/<slug>.js
    stylesheets/common/<slug>.scss
  .circleci/
    config.yml
  .github/workflows/
    lint.yml
  docker/
    docker-compose.yml
    Dockerfile
    entrypoint.sh
  .eslintrc.json
  .stylelintrc.json
  .rubocop.yml
  package.json
  Gemfile
  .gitignore

Theme:

<slug>/
  about.json
  assets/
    stylesheets/common/<slug>.scss
  .circleci/
    config.yml
  .github/workflows/
    lint.yml
  docker/
    docker-compose.yml
    Dockerfile
    entrypoint.sh
  .eslintrc.json
  .stylelintrc.json
  package.json
  .gitignore

Linting

JavaScript and CSS (plugin or theme):

npm install
npm run lint       # runs lint:js and lint:css

Ruby (plugin only):

bundle install --path vendor/bundle
npm run lint:rb    # runs `bundle exec rubocop`

Notes:

• ESLint is configured with Standard style; the script tolerates missing JS files.
• Stylelint uses the Standard config and checks assets/stylesheets/**/*.scss.
• RuboCop may require native gem compilation; ensure a C compiler and headers are installed (e.g., xcode-select --install on macOS), or use a modern Ruby via rbenv/rvm.

Using the Plugin in Discourse

• Place the generated plugin folder under your Discourse repo plugins/ directory.
• Restart your Discourse dev server.
• The scaffold registers a stylesheet and defines a namespaced module for extension.

Run with Docker (Plugin)

• cd <slug>
• Optional: set DISCOURSE_VERSION in your shell to stable, a tag, or branch
• docker compose up -d to start Postgres, Redis, and Discourse dev server
• Access Discourse at http://localhost:3000/ with the plugin mounted under /app/plugins/<slug> inside the container

Using the Theme in Discourse

• Zip the theme folder and upload it via Discourse Admin → Customize → Themes.
• Alternatively, commit to a repository and install by URL.

Run with Docker (Theme)

• cd <slug>
• Optional: set DISCOURSE_VERSION in your shell
• docker compose up -d to start Postgres, Redis, and Discourse dev server
• The theme is mounted under /app/themes/<slug>; install via Admin → Customize → Themes

Troubleshooting

• ESLint: "No files matching the pattern" → handled by --no-error-on-unmatched-pattern in scripts.
• Stylelint: empty source/errors → the scaffold includes a minimal :root rule to avoid empty blocks.
• RuboCop native gems (e.g., json) fail to install → install dev tools and/or use rbenv/rvm with bundle install --path vendor/bundle.
• Yarn/Corepack: If you see errors about packageManager and Yarn versions, enable Corepack before installing dependencies:
  • corepack enable
  • Optional: corepack prepare yarn@stable --activate
  • In Docker, the entrypoint enables Corepack automatically.

Roadmap

• Additional Discourse plugin templates (settings, serializers, server‑side classes) and theme templates (common/desktop/mobile).

Author

• Arun Chaitanya Jami

License

• MIT