Stone.js - CLI

The official CLI tool for building, running, and managing Stone.js applications.

Overview

Stone CLI is the primary interface for creating and managing Stone.js projects.
It provides a powerful set of built-in commands to bootstrap apps, serve them locally, build for production, and more.

Whether you're developing a backend microservice, a frontend SPA, a fullstack SSR app, or a CLI tool powered by Stone.js, the CLI helps you get started quickly and stay productive.

Key Features

• Create and scaffold new Stone.js apps interactively
• Run development servers with hot reload
• Build production bundles and preview them
• Export third-party toolchain configs (e.g., Rollup, Vite)
• Type checking and cache clearing
• Discover and run custom commands defined in your app or installed libraries
• Let any package participate in the build with an agnostic plugin system
• Let any package own a build target outright, so a module decides how its applications are built

Plugins: participate in the build

The CLI is itself a Stone.js app, and it lets any package take part in the build and bundle through an agnostic StoneCliPlugin contract. A plugin can run config-phase middleware, generate code into .stone/ and contribute modules or configuration to the built app, all without knowing anything about the CLI internals.

// @acme/stone-acme/cli
export function acmeCliPlugin (options = {}) {
  return {
    name: '@acme/stone-acme',
    onPrepare (ctx) {
      ctx.writeFile('plugins/acme.mjs', "export const acme = defineConfig({ stone: { acme: {} } })")
      ctx.addModule('./plugins/acme.mjs') // its exports join the app modules
    }
  }
}

Load a plugin explicitly from stone.config (open to any package):

import { defineBuilderConfig } from '@stone-js/cli'
import { acmeCliPlugin } from '@acme/stone-acme/cli'

export default defineBuilderConfig({ plugins: [acmeCliPlugin()] })

First-party @stone-js/* packages that advertise a stone.cliPlugin contract in their package.json are auto-discovered from your direct dependencies, so they stay truly zero-config. Third-party plugins always go through stone.config, and every auto-discovered plugin is announced on each build. Opt out with autoDiscoverPlugins: false.

Full guide: Participate in the build.

Build targets: own your build

A plugin can go further and own a build outright. The CLI knows when to call a builder and nothing about what it does, so a module decides how its own applications are built:

import { defineBuilderConfig } from '@stone-js/cli'

export default defineBuilderConfig({
  builders: {
    acme: {
      target: 'acme',
      priority: 20,
      match: (blueprint, event) => true,      // detection only; --target wins over this
      resolver: (context) => new AcmeBuilder(context),
      devMode: 'self-hosted',                  // your dev server reloads itself
      previewEntry: (blueprint) => 'dist/acme.mjs'
    }
  }
})

Then stone build --target acme, stone serve acme, stone preview acme all drive it. Every step (build, dev, preview, console, export, watchFiles) is optional, and a command tells the user plainly when a target does not support the one it needs.

The two targets the CLI ships with, react and server, are registered through this exact key. Precedence when nobody names one: --target, then stone.builder.target, then each target's match in priority order, with the backend target answering last.

Installation

npm install -g @stone-js/cli

You can also use it locally via npx:

npx stone

Once installed, try:

stone --help

Learn More

This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.

Explore the full documentation: https://stonejs.dev

API documentation

• API

Contributing

See Contributing Guide