# 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