@stone-js/starters 0.8.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Stone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# Stone.js - Starters
+
+[![License: MIT](https://img.shields.io/npm/l/@stone-js/starters)](https://opensource.org/licenses/MIT)
+[![Maintenance](https://img.shields.io/maintenance/yes/2026)](https://stonejs.dev)
+[![Used by Stone CLI](https://img.shields.io/badge/Used%20by-Stone%20CLI-blue)](https://github.com/stone-foundation/stone-js-cli)
+
+This repository contains official **starter templates** for Stone.js applications.
+
+--- 
+
+## Overview
+
+It is used internally by the Stone CLI to generate scaffolded projects for both **microservices** and **frontend React apps**, with three predefined levels of complexity: **basic**, **standard**, and **full**.
+
+## Available Starters
+
+Each starter reflects a different level of complexity and domain (microservice or React), with both declarative and imperative styles available. You can pick the one that matches your architecture preferences and scale needs.
+
+### Microservice Starters
+
+| Name                           | Description                                                        |
+| ------------------------------ | ------------------------------------------------------------------ |
+| `basic-service-declarative`    | Minimal Stone.js microservice using class and decorators           |
+| `basic-service-imperative`     | Minimal functional microservice with handler and blueprint         |
+| `standard-service-declarative` | Adds routing, DI, and hooks with a clean declarative structure     |
+| `standard-service-imperative`  | Functional routing setup with middleware and service container     |
+| `full-service-declarative`     | Production-grade setup: lifecycle hooks, DI, error handling, tests |
+| `full-service-imperative`      | Complete functional microservice with config, tests, and events    |
+
+### React App Starters
+
+| Name                         | Description                                                              |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `basic-react-declarative`    | Minimal React + Stone.js (SPA/SSR-ready) using class-based API           |
+| `basic-react-imperative`     | Minimal React app using functional API and manual config                 |
+| `standard-react-declarative` | Adds layout, routing, and lifecycle via decorators                       |
+| `standard-react-imperative`  | Function-based setup with routing, layout system, and render control     |
+| `full-react-declarative`     | Enterprise-ready app with head config, hydration, and complete structure |
+| `full-react-imperative`      | Full functional React app with SSR, hooks, tests, and platform config    |
+
+You can combine complexity level (`basic`, `standard`, `full`), domain (`react`, `service`), and style (`declarative`, `imperative`) to find the right starter, for example: `standard-react-imperative`.
+
+
+## How It's Used
+
+These starters are **not meant to be installed manually**.
+
+Instead, the `@stone-js/cli` automatically pulls from this repository during:
+
+```bash
+npm create @stone-js
+````
+
+or
+
+```bash
+stone init
+```
+
+The CLI fetches the appropriate template based on user choices and sets up a ready-to-run project in seconds.
+
+## Starter Structure
+
+Each starter is a self-contained folder containing:
+
+* `app/`, `asset/`, `public/`, `tests/` depending on the type
+* Minimal `stone.config.mjs` or framework config
+* Preset integration (e.g. adapters, blueprint, lifecycle)
+* Preconfigured TypeScript + Vitest (for standard/full)
+* Working example of event handler or route
+
+## Maintaining the Starters
+
+To update or add a new starter:
+
+1. Fork or clone this repository.
+2. Add or modify the corresponding folder (e.g., `react-full`, `micro-basic`).
+3. Keep external dependencies minimal.
+4. Test the template using the CLI locally.
+5. Submit a PR following the [Contributing Guide](./CONTRIBUTING.md).
+
+> The Stone CLI will always fetch the latest `main` branch when scaffolding.
+
+## Why Three Levels?
+
+Stone.js follows a **progressive complexity** approach.
+These templates help developers grow their app without needing to eject or reconfigure from scratch.
+
+* **Basic**: Hello world in 10 seconds.
+* **Standard**: Real-world app features with good defaults.
+* **Full**: Production-grade architecture with opinions.
+
+## 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](https://stonejs.dev)
+
+## Contributing
+
+See [Contributing Guide](https://github.com/stone-foundation/stone-js-starters/blob/main/CONTRIBUTING.md)

package/basic-react-declarative/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Stone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/basic-react-declarative/README.md

@@ -0,0 +1,39 @@
+# Stone.js - Basic starter
+
+Stone.js's basic starter to create react app using declarative API.
+
+## Project Setup
+
+```sh
+npm install
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+npm run dev
+```
+
+### Compile and Bundle for Production
+
+```sh
+npm run build
+```
+
+### Run the Production build
+
+```sh
+npm run preview
+```
+
+### Run tests
+
+```sh
+npm run test
+```
+
+### Run tests with coverage
+
+```sh
+npm run test:cvg
+```

package/basic-react-declarative/app/Application.tsx

@@ -0,0 +1,89 @@
+import { JSX } from 'react'
+import { Browser } from '@stone-js/browser-adapter'
+import { NodeConsole } from '@stone-js/node-cli-adapter'
+import { ILogger, LogLevel, Promiseable, StoneApp } from '@stone-js/core'
+import { ReactIncomingEvent, UseReact, HeadContext, IPage, PageHeadContext, PageRenderContext } from '@stone-js/use-react'
+
+/**
+ * Application
+ *
+ * This is the main application entry point.
+ *
+ * @UseReact() is used to enable React.
+ * @Browser() is used to enable the Browser adapter.
+ * @StoneApp() is used to enable the Stone application, it is required.
+ */
+@Browser()
+@UseReact()
+@NodeConsole()
+@StoneApp({ logger: { level: LogLevel.INFO } })
+export class Application implements IPage<ReactIncomingEvent> {
+  /**
+   * Logger is a service for logging.
+  */
+  private readonly logger: ILogger
+
+  /**
+   * Create a new instance of Application
+   * At this point, all the dependencies are resolved and injected.
+   * You can access the container and all the services.
+   *
+   * @param logger - Logger service.
+  */
+  constructor ({ logger }: { logger: ILogger }) {
+    this.logger = logger
+  }
+
+  /**
+   * Handle incoming events
+   *
+   * @param event Incoming event
+   * @returns response
+  */
+  handle (event: ReactIncomingEvent): ResponseData {
+    // Get the name from the event
+    const message = `Hello ${String(event.get<string>('name', 'World'))}!`
+
+    // Log a message
+    this.logger.info(message)
+
+    // Return a JSON response
+    return { message }
+  }
+
+  /**
+   * Set the page head tags, like title, meta, link, script, style.
+   *
+   * @returns The head context.
+   */
+  head ({ event }: PageHeadContext): Promiseable<HeadContext> {
+    return {
+      title: `Hello ${String(event.get<string>('name', 'World'))}!`,
+      description: 'This is a simple example of a React application using Stone.js',
+      metas: [
+        { name: 'author', content: 'Stone.js' },
+        { name: 'keywords', content: 'stonejs,js,react,example' }
+      ]
+    }
+  }
+
+  /**
+   * Render the component.
+   *
+   * @returns The rendered component.
+   */
+  render ({ data }: PageRenderContext<ResponseData>): JSX.Element {
+    return (
+      <section className='container'>
+        <h1 className='h1 text-center mt-64'>{data?.message}</h1>
+      </section>
+    )
+  }
+}
+
+/**
+ * Response data
+ */
+export interface ResponseData {
+  message: string
+}

package/basic-react-declarative/assets/css/index.css

@@ -0,0 +1,26 @@
+body {
+  margin: 0;
+  padding: 0;
+  color: #333;
+  font-size: 14px;
+  line-height: 1.5;
+  background-color: #fff;
+  font-family: 'Roboto', sans-serif;
+}
+.h1 {
+  margin: 0;
+  font-size: 3rem;
+  font-weight: 500;
+  font-weight: bold;
+}
+.container {
+  width: 100vw;
+  display: flex;
+  justify-content: center;
+}
+.text-center {
+  text-align: center;
+}
+.mt-64 {
+  margin-top: 64px;
+}

package/basic-react-declarative/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "basic-react-declarative",
+  "private": true,
+  "version": "1.0.0",
+  "description": "Stone.js's basic starter to create react app using declarative API.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "stone dev",
+    "build": "stone build",
+    "preview": "stone preview",
+    "build:ssr": "stone build --ssr",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@stone-js/core": "^0.8.3",
+    "@stone-js/use-react": "^0.8.3",
+    "@stone-js/browser-adapter": "^0.8.3",
+    "@stone-js/node-cli-adapter": "^0.8.3"
+  },
+  "devDependencies": {
+    "@babel/plugin-proposal-decorators": "^7.25.9",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-typescript": "^7.27.0",
+    "@stone-js/cli": "^0.8.3",
+    "@types/node": "^24.0.7",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "@vitest/coverage-v8": "^3.0.9",
+    "vitest": "^3.0.9"
+  }
+}

package/basic-react-declarative/tests/Application.spec.ts

@@ -0,0 +1,96 @@
+import { ILogger } from '@stone-js/core'
+import { Application } from '../app/Application'
+import { renderToString } from 'react-dom/server'
+import { ReactIncomingEvent } from '@stone-js/use-react'
+
+// We must mock decorators to lighten the test environment
+vi.mock('@stone-js/core', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    StoneApp: vi.fn(() => vi.fn()),
+  }
+})
+
+// We must mock decorators to lighten the test environment
+vi.mock('@stone-js/node-cli-adapter', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    NodeConsole: vi.fn(() => vi.fn()),
+  }
+})
+
+// We must mock decorators to lighten the test environment
+vi.mock('@stone-js/browser-adapter', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    Browser: vi.fn(() => vi.fn()),
+  }
+})
+
+// We must mock decorators to lighten the test environment
+vi.mock('@stone-js/use-react', async (importOriginal) => {
+  const actual: any = await importOriginal()
+  return {
+    ...actual,
+    UseReact: vi.fn(() => vi.fn()),
+  }
+})
+
+describe('Application', () => {
+  let app: Application
+  let mockedLogger: ILogger
+
+  beforeEach(() => {
+    mockedLogger = {
+      info: vi.fn(),
+    } as unknown as ILogger
+
+    app = new Application({ logger: mockedLogger })
+  })
+
+  it('should create an application instance', () => {
+    // Assert
+    expect(app).toBeInstanceOf(Application)
+  })
+
+  it('get head values', async () => {
+    // Arrange
+    const expectedMessage = 'Hello World!'
+    const event = { get: () => 'World' } as unknown as ReactIncomingEvent
+
+    // Act
+    const head = await app.head({ event })
+
+    // Assert
+    expect(head).toHaveProperty('metas')
+    expect(head.title).toBe(expectedMessage)
+    expect(head).toHaveProperty('description')
+  })
+
+  it('should handle incoming events', () => {
+    // Arrange
+    const expectedMessage = 'Hello World!'
+    const event = { get: () => 'World' } as unknown as ReactIncomingEvent
+
+    // Act
+    const response = app.handle(event) as { message: string }
+
+    // Assert
+    expect(response.message).toBe(expectedMessage)
+    expect(mockedLogger.info).toHaveBeenCalledWith(expectedMessage)
+  })
+
+  it('should render component', () => {
+    // Arrange
+    const message = 'Hello World!'
+
+    // Act
+    const response = renderToString(app.render({ data: { message } } as any))
+
+    // Assert
+    expect(response).toMatchSnapshot()
+  })
+})

package/basic-react-declarative/tests/__snapshots__/Application.spec.ts.snap

@@ -0,0 +1,3 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Application > should render component 1`] = `"<section class="container"><h1 class="h1 text-center mt-64">Hello World!</h1></section>"`;

package/basic-react-declarative/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "experimentalDecorators": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "resolveJsonModule": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+
+    "types": ["node", "vite/client", "vitest/globals"],
+  },
+  "include": [
+    "app",
+    "tests",
+    "vitest.config.ts"
+  ]
+}

package/basic-react-declarative/vitest.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['./tests/**/*.{test,spec}.?(c|m)[jt]s?(x)'],
+    coverage: {
+      provider: 'v8',
+      include: ['app/**/*.ts', 'app/**/*.tsx'],
+      reporter: ['text', 'html'],
+      reportsDirectory: './coverage',
+      thresholds: {
+        100: true
+      },
+      watermarks: {
+        statements: [60, 80],
+        functions: [60, 80],
+        branches: [60, 80],
+        lines: [60, 80]
+      }
+    },
+  }
+});

package/basic-react-imperative/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Stone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/basic-react-imperative/README.md

@@ -0,0 +1,39 @@
+# Stone.js - Basic starter
+
+Stone.js's basic starter to create react app using imperative API.
+
+## Project Setup
+
+```sh
+npm install
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+npm run dev
+```
+
+### Compile and Bundle for Production
+
+```sh
+npm run build
+```
+
+### Run the Production build
+
+```sh
+npm run preview
+```
+
+### Run tests
+
+```sh
+npm run test
+```
+
+### Run tests with coverage
+
+```sh
+npm run test:cvg
+```

package/basic-react-imperative/app/Application.tsx

@@ -0,0 +1,89 @@
+import { JSX } from 'react'
+import { browserAdapterBlueprint } from '@stone-js/browser-adapter'
+import { defineConfig, IBlueprint, ILogger, isNotEmpty, Promiseable } from '@stone-js/core'
+import { defineCommand, FactoryCommandHandler, NODE_CONSOLE_PLATFORM, nodeConsoleAdapterBlueprint } from '@stone-js/node-cli-adapter'
+import { defineStoneReactApp, HeadContext, IPage, PageHeadContext, PageRenderContext, ReactIncomingEvent } from '@stone-js/use-react'
+
+/**
+ * Create an handler using the factory handler.
+ */
+export const FactoryHandler = ({ logger }: AppOptions): IPage<ReactIncomingEvent> => {
+  return {
+    handle (event: ReactIncomingEvent): ResponseData {
+      // Get the name from the event
+      const message = `Hello ${String(event.get<string>('name', 'World'))}!`
+
+      // Log a message
+      logger.info(message)
+
+      // Return a JSON response
+      return { message }
+    },
+
+    /**
+     * Set the page head tags, like title, meta, link, script, style.
+     *
+     * @returns The head context.
+     */
+    head ({ event }: PageHeadContext): Promiseable<HeadContext> {
+      return {
+        title: `Hello ${String(event.get<string>('name', 'World'))}!`,
+        description: 'This is a simple example of a React application using Stone.js',
+        metas: [
+          { name: 'author', content: 'Stone.js' },
+          { name: 'keywords', content: 'stonejs,js,react,example' }
+        ]
+      }
+    },
+
+    /**
+     * Render the component.
+     *
+     * @returns The rendered component.
+     */
+    render ({ data }: PageRenderContext<ResponseData>): JSX.Element {
+      return (
+        <section className='container'>
+          <h1 className='h1 text-center mt-64'>{data?.message}</h1>
+        </section>
+      )
+    }
+  }
+}
+
+/**
+ * Stone-React application.
+ */
+export const Application = defineStoneReactApp(
+  FactoryHandler,
+  { debug: true, isFactory: true },
+  [browserAdapterBlueprint, nodeConsoleAdapterBlueprint]
+)
+
+/**
+ * Application configuration.
+ */
+export const AppConfig = defineConfig({
+  afterConfigure (blueprint: IBlueprint) {
+    if (
+      isNotEmpty<FactoryCommandHandler>(FactoryHandler) &&
+      blueprint.is('stone.adapter.platform', NODE_CONSOLE_PLATFORM)
+    ) {
+      blueprint.set(defineCommand(FactoryHandler, { name: '*', isFactory: true }))
+    }
+  }
+})
+
+/**
+ * Application options.
+ */
+interface AppOptions {
+  logger: ILogger
+}
+
+/**
+ * Response data
+ */
+interface ResponseData {
+  message: string
+}

package/basic-react-imperative/assets/css/index.css

@@ -0,0 +1,26 @@
+body {
+  margin: 0;
+  padding: 0;
+  color: #333;
+  font-size: 14px;
+  line-height: 1.5;
+  background-color: #fff;
+  font-family: 'Roboto', sans-serif;
+}
+.h1 {
+  margin: 0;
+  font-size: 3rem;
+  font-weight: 500;
+  font-weight: bold;
+}
+.container {
+  width: 100vw;
+  display: flex;
+  justify-content: center;
+}
+.text-center {
+  text-align: center;
+}
+.mt-64 {
+  margin-top: 64px;
+}