Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
import fs from 'node:fs'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import * as p from '@clack/prompts'
import { type Command, Option } from 'commander'
import { execa } from 'execa'
import pc from 'picocolors'
import { warnDeprecated } from '../deprecation.js'
import { PLUGIN_PEER_RANGES } from '../lib/plugin-peer-ranges.js'
import { render, type TemplateVars } from '../lib/template.js'
const TEMPLATE_RELATIVE_PATH = '../../templates/plugin'
interface PluginNewFlags {
dashboard: boolean
backend: boolean
engine: boolean
install: boolean
force: boolean
yes: boolean
backendName?: string
rubyName?: string
moduleName?: string
npmScope?: string
author?: string
authorEmail?: string
license?: string
}
const LICENSES = ['MIT', 'Apache-2.0', 'BSD-3-Clause'] as const
export function registerPluginCommand(program: Command): void {
const plugin = program
.command('plugin')
.description('Scaffold and manage Spree plugins (dashboard + backend)')
plugin
.command('new')
.description(
'Scaffold a new Spree plugin monorepo (dashboard plugin half today; backend half coming soon)',
)
.argument('[name]', 'Plugin name (e.g. brands). If omitted, you will be prompted.')
.option('--backend-name <name>', 'Backend package name (default: spree_<name>)')
.addOption(new Option('--ruby-name <name>').hideHelp())
.option(
'--module-name <name>',
'Backend module / TS namespace (default: PascalCase of the backend package name)',
)
.option('--npm-scope <scope>', 'npm scope, e.g. @acme (default: unscoped)')
.option('--author <name>', 'Author name (default: git config user.name)')
.option('--author-email <email>', 'Author email (default: git config user.email)')
.option('--license <license>', `License: ${LICENSES.join(', ')} (default: MIT)`)
.option(
'-y, --yes',
'Non-interactive: accept the default for every prompt not answered by a flag',
false,
)
.option('--no-dashboard', 'Skip the dashboard plugin half')
.option(
'--no-backend',
'Skip the backend half (currently always skipped — backend support coming soon)',
)
.addOption(new Option('--no-engine').hideHelp())
.option('--no-install', 'Skip running pnpm install')
.option('--force', 'Overwrite a non-empty destination directory')
.action(async (nameArg: string | undefined, flags: PluginNewFlags) => {
p.intro(pc.bgCyan(pc.black(' Spree Plugin Scaffolder ')))
if (flags.rubyName) {
warnDeprecated('--ruby-name', '--backend-name')
flags.backendName ??= flags.rubyName
}
if (flags.engine === false) {
warnDeprecated('--no-engine', '--no-backend')
flags.backend = false
}
const answers = await collectAnswers(nameArg, flags)
if (p.isCancel(answers)) {
p.cancel('Scaffolding cancelled.')
process.exit(0)
}
const dst = path.resolve(process.cwd(), answers.name)
if (fs.existsSync(dst) && fs.readdirSync(dst).length > 0 && !flags.force) {
p.cancel(
`Destination ${pc.bold(dst)} is not empty. Choose a different name or rerun with ${pc.cyan('--force')}.`,
)
process.exit(1)
}
const vars = buildVars(answers)
const templateSrc = resolveTemplatePath()
const s = p.spinner()
s.start(`Scaffolding ${pc.cyan(answers.name)}...`)
try {
render({
src: templateSrc,
dst,
vars,
skip: buildSkipPredicate(answers),
force: flags.force,
})
} catch (err) {
s.stop('Scaffolding failed.')
p.log.error(err instanceof Error ? err.message : String(err))
process.exit(1)
}
s.stop(`Created ${pc.cyan(dst)}`)
if (flags.install) {
await runInstall(dst, answers)
} else {
p.log.info(pc.dim('Skipping dependency install — run them yourself when ready.'))
}
printNextSteps(answers, dst, flags.install)
p.outro('Happy hacking!')
})
}
// ---------------------------------------------------------------------------
// Prompts + flag parsing
// ---------------------------------------------------------------------------
interface Answers {
name: string
rubyName: string
moduleName: string
npmScope: string
authorName: string
authorEmail: string
license: string
includeDashboard: boolean
includeEngine: boolean
}
async function collectAnswers(
nameArg: string | undefined,
flags: PluginNewFlags,
): Promise<Answers | typeof p.CANCEL_SYMBOL> {
const validateName = (value: string | undefined): string | undefined => {
if (!value) return 'Required'
if (!/^[a-z][a-z0-9-]*$/.test(value)) {
return 'Use lowercase letters, digits, and dashes (e.g. "brands" or "loyalty-points")'
}
return undefined
}
if (nameArg !== undefined) {
const problem = validateName(nameArg)
if (problem) {
p.log.error(`Invalid plugin name ${pc.bold(nameArg)}: ${problem}`)
process.exit(2)
}
}
if (nameArg === undefined && flags.yes) {
p.log.error('Pass the plugin name as an argument when using --yes: spree plugin new <name> -y')
process.exit(2)
}
const name =
nameArg ??
(await p.text({
message: 'Plugin name',
placeholder: 'brands',
validate: validateName,
}))
if (p.isCancel(name)) return name
// Every prompt below can be pre-answered by a flag; --yes accepts the
// default for whatever the flags leave unanswered.
const rubyDefault = `spree_${(name as string).replace(/-/g, '_')}`
const rubyName = await resolveField({
flag: '--backend-name',
flagValue: flags.backendName,
fallback: rubyDefault,
yes: flags.yes,
validate: (value) =>
value && /^[a-z][a-z0-9_]*$/.test(value)
? undefined
: 'Use lowercase letters, digits, and underscores (e.g. "spree_brands")',
prompt: () =>
p.text({
message: 'Backend package name (Ruby gem)',
placeholder: rubyDefault,
initialValue: rubyDefault,
validate: (value) =>
value && /^[a-z][a-z0-9_]*$/.test(value)
? undefined
: 'Use lowercase letters, digits, and underscores (e.g. "spree_brands")',
}),
})
if (p.isCancel(rubyName)) return rubyName
const moduleDefault = pascalCase(rubyName as string)
const moduleName = await resolveField({
flag: '--module-name',
flagValue: flags.moduleName,
fallback: moduleDefault,
yes: flags.yes,
validate: (value) =>
value && /^[A-Z][A-Za-z0-9]*$/.test(value) ? undefined : 'PascalCase (e.g. "SpreeBrands")',
prompt: () =>
p.text({
message: 'Ruby module / TS namespace',
placeholder: moduleDefault,
initialValue: moduleDefault,
validate: (value) =>
value && /^[A-Z][A-Za-z0-9]*$/.test(value)
? undefined
: 'PascalCase (e.g. "SpreeBrands")',
}),
})
if (p.isCancel(moduleName)) return moduleName
const validateScope = (value: string | undefined): string | undefined =>
!value || /^@[a-z0-9][a-z0-9-]*$/.test(value)
? undefined
: 'Must start with @ and contain lowercase letters/digits/dashes'
const npmScope = await resolveField({
flag: '--npm-scope',
flagValue: flags.npmScope,
fallback: '',
yes: flags.yes,
validate: validateScope,
prompt: () =>
p.text({
message: 'npm scope (optional, leave blank for unscoped)',
placeholder: '@my-org',
initialValue: '',
validate: validateScope,
}),
})
if (p.isCancel(npmScope)) return npmScope
// Author identity defaults to the local git config — the same values a
// `git commit` in this shell would stamp.
const gitAuthor = flags.author === undefined ? await gitConfigValue('user.name') : undefined
const authorName = await resolveField({
flag: '--author',
flagValue: flags.author,
fallback: gitAuthor,
yes: flags.yes,
validate: (value) => (value ? undefined : 'Required'),
prompt: () =>
p.text({
message: 'Author name',
placeholder: 'Jane Developer',
initialValue: gitAuthor ?? '',
validate: (value) => (value ? undefined : 'Required'),
}),
})
if (p.isCancel(authorName)) return authorName
const validateEmail = (value: string | undefined): string | undefined =>
value && /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value) ? undefined : 'Enter a valid email'
const gitEmail = flags.authorEmail === undefined ? await gitConfigValue('user.email') : undefined
const authorEmail = await resolveField({
flag: '--author-email',
flagValue: flags.authorEmail,
fallback: gitEmail,
yes: flags.yes,
validate: validateEmail,
prompt: () =>
p.text({
message: 'Author email',
placeholder: '[email protected]',
initialValue: gitEmail ?? '',
validate: validateEmail,
}),
})
if (p.isCancel(authorEmail)) return authorEmail
const validateLicense = (value: string | undefined): string | undefined =>
value && (LICENSES as readonly string[]).includes(value)
? undefined
: `Must be one of: ${LICENSES.join(', ')}`
const license = await resolveField({
flag: '--license',
flagValue: flags.license,
fallback: 'MIT',
yes: flags.yes,
validate: validateLicense,
prompt: () =>
p.select({
message: 'License',
options: LICENSES.map((value) => ({ value: value as string, label: value })),
initialValue: 'MIT',
}),
})
if (p.isCancel(license)) return license
// The `--no-dashboard` flag pre-answers this; --yes accepts the default.
const includeDashboard =
flags.dashboard === false
? false
: flags.yes || (await promptConfirm('Include dashboard plugin?', true))
if (p.isCancel(includeDashboard)) return includeDashboard
// The engine half is not yet generated by the CLI — the Rails templates
// land in a follow-up PR. For now, we always answer false and note it.
// Once the engine templates exist, restore the prompt:
//
// const includeEngine = flags.backend === false
// ? false
// : await promptConfirm('Include Rails engine (API endpoints)?', true)
const includeEngine = false
if (flags.backend !== false) {
p.log.warn(
'Backend generation is coming in a future release. For now, scaffold the dashboard half here and use `spree-extension create` for the backend side.',
)
}
if (!includeDashboard && !includeEngine) {
p.cancel('Nothing to scaffold (dashboard half declined).')
process.exit(1)
}
return {
name: name as string,
rubyName: rubyName as string,
moduleName: moduleName as string,
npmScope: (npmScope as string).trim(),
authorName: authorName as string,
authorEmail: authorEmail as string,
license: license as string,
includeDashboard: includeDashboard as boolean,
includeEngine: includeEngine as boolean,
}
}
async function promptConfirm(message: string, initial: boolean): Promise<boolean | symbol> {
const result = await p.confirm({ message, initialValue: initial })
return result
}
interface FieldSpec {
/** Flag name for error messages, e.g. `--author`. */
flag: string
/** Value supplied via the flag, if any. Wins over everything; validated. */
flagValue: string | undefined
/** Default used by --yes and prefilled into the interactive prompt. */
fallback: string | undefined
/** True when running with --yes (accept fallback instead of prompting). */
yes: boolean
validate: (value: string | undefined) => string | undefined
prompt: () => Promise<string | symbol>
}
/**
* Resolve one scaffold answer from, in order: an explicit flag, the --yes
* default, or an interactive prompt. Invalid flag values and --yes runs with
* no usable default exit with a usage error rather than falling back to a
* prompt — non-interactive means non-interactive.
*/
async function resolveField(spec: FieldSpec): Promise<string | symbol> {
if (spec.flagValue !== undefined) {
const problem = spec.validate(spec.flagValue)
if (problem) {
p.log.error(`Invalid value for ${pc.cyan(spec.flag)}: ${problem}`)
process.exit(2)
}
return spec.flagValue
}
if (spec.yes) {
const problem = spec.validate(spec.fallback)
if (spec.fallback === undefined || problem) {
p.log.error(
`--yes could not resolve a default for ${pc.cyan(spec.flag)}` +
(problem ? ` (${problem})` : '') +
` — pass ${pc.cyan(spec.flag)} explicitly.`,
)
process.exit(2)
}
return spec.fallback
}
return spec.prompt()
}
/** Read a git config value, returning undefined when unset or git is absent. */
async function gitConfigValue(key: string): Promise<string | undefined> {
try {
const { stdout } = await execa('git', ['config', '--get', key])
const value = stdout.trim()
return value || undefined
} catch {
return undefined
}
}
// ---------------------------------------------------------------------------
// Template variable + skip-predicate builders
// ---------------------------------------------------------------------------
function buildVars(a: Answers): TemplateVars {
const npmPackageName = a.npmScope ? `${a.npmScope}/${a.name}` : a.name
return {
name: a.name,
plugin_name: a.name,
ruby_name: a.rubyName,
module_name: a.moduleName,
npm_scope: a.npmScope,
npm_package_name: npmPackageName,
npm_dashboard_package: a.npmScope ? `${a.npmScope}/${a.name}-dashboard` : `${a.name}-dashboard`,
author_name: a.authorName,
author_email: a.authorEmail,
license: a.license,
year: String(new Date().getFullYear()),
...PLUGIN_PEER_RANGES,
}
}
function buildSkipPredicate(a: Answers): (relPath: string) => boolean {
const skipDashboard = !a.includeDashboard
const skipEngine = !a.includeEngine
return (rel) => {
if (skipDashboard && (rel === 'packages/dashboard' || rel.startsWith('packages/dashboard/'))) {
return true
}
if (skipEngine && (rel === 'engine' || rel.startsWith('engine/'))) return true
return false
}
}
// ---------------------------------------------------------------------------
// Post-scaffold install + banner
// ---------------------------------------------------------------------------
async function runInstall(dst: string, answers: Answers): Promise<void> {
const s = p.spinner()
if (answers.includeDashboard) {
s.start('Running pnpm install...')
try {
await execa('pnpm', ['install'], { cwd: dst, stdio: 'pipe' })
s.stop('pnpm install complete.')
} catch (err) {
s.stop(pc.yellow('pnpm install failed — run it manually.'))
p.log.warn(err instanceof Error ? err.message : String(err))
}
}
if (answers.includeEngine) {
s.start('Running bundle install in engine/...')
try {
await execa('bundle', ['install'], { cwd: path.join(dst, 'engine'), stdio: 'pipe' })
s.stop('bundle install complete.')
} catch (err) {
s.stop(pc.yellow('bundle install failed — run it manually.'))
p.log.warn(err instanceof Error ? err.message : String(err))
}
}
}
function printNextSteps(answers: Answers, dst: string, installed: boolean): void {
const lines: string[] = ['']
lines.push(pc.bold('Next steps'))
lines.push(` ${pc.dim('cd')} ${path.relative(process.cwd(), dst) || '.'}`)
if (!installed) {
if (answers.includeDashboard) lines.push(` ${pc.dim('pnpm')} install`)
if (answers.includeEngine)
lines.push(` ${pc.dim('cd engine && bundle')} install && ${pc.dim('cd ..')}`)
}
if (answers.includeDashboard) {
lines.push('')
lines.push(pc.bold('Dashboard plugin'))
lines.push(
` Edit ${pc.cyan('packages/dashboard/src/index.tsx')} to register nav entries and slot widgets.`,
)
lines.push(
` Add pages as file routes in ${pc.cyan('packages/dashboard/src/routes/')} — compiled into the host's typed route tree.`,
)
lines.push(
` See ${pc.cyan('https://spreecommerce.org/docs/developer/dashboard/plugins/overview')}`,
)
}
if (answers.includeEngine) {
lines.push('')
lines.push(pc.bold('Rails engine'))
lines.push(
` Edit ${pc.cyan(`engine/app/controllers/spree/api/v3/admin/${answers.rubyName}_controller.rb`)}`,
)
lines.push(
` See ${pc.cyan('https://spreecommerce.org/docs/developer/contributing/creating-an-extension')}`,
)
}
const installArgs = [
...(answers.includeEngine ? ['--gem', answers.rubyName] : []),
...(answers.includeDashboard ? ['--npm', buildVars(answers).npm_dashboard_package] : []),
]
if (installArgs.length > 0) {
lines.push('')
lines.push(pc.bold('Installing it in a Spree project, once published'))
lines.push(` ${pc.cyan(['spree add', ...installArgs].join(' '))}`)
}
lines.push('')
p.note(lines.join('\n'), 'Your plugin is scaffolded.')
}
// ---------------------------------------------------------------------------
// Utilities
// ---------------------------------------------------------------------------
function pascalCase(input: string): string {
return input
.split(/[_-]/)
.filter(Boolean)
.map((part) => part[0].toUpperCase() + part.slice(1))
.join('')
}
/**
* The bundled template lives next to the CLI's dist/ in the published
* tarball (`dist/templates/plugin/`) and next to source in dev
* (`packages/cli/templates/plugin/`). Resolve relative to this file so
* both layouts work.
*/
function resolveTemplatePath(): string {
const here = path.dirname(fileURLToPath(import.meta.url))
// dev: src/commands/plugin.ts → templates/plugin/ via ../../templates/plugin
// built: dist/index.js → dist/templates/plugin/ (tsup copies templates into
// dist/ on build; the tarball only ships dist/)
const candidates = [
path.resolve(here, TEMPLATE_RELATIVE_PATH),
path.resolve(here, 'templates/plugin'),
]
for (const candidate of candidates) {
if (fs.existsSync(candidate)) return candidate
}
throw new Error(
`Plugin template not found. Looked in:\n ${candidates.join('\n ')}\n\nReinstall @spree/cli to fix.`,
)
}