@stone-js/starters 0.8.3

package/basic-service-imperative/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'],
+      reporter: ['text', 'html'],
+      reportsDirectory: './coverage',
+      thresholds: {
+        100: true
+      },
+      watermarks: {
+        statements: [60, 80],
+        functions: [60, 80],
+        branches: [60, 80],
+        lines: [60, 80]
+      }
+    },
+  }
+});

package/continuum-showcase/README.md

@@ -0,0 +1,44 @@
+# continuum-showcase
+
+A small example app that exercises the frontend features added in the 2026-07 continuum pass.
+It doubles as a manual test bed for the new APIs.
+
+## What it demonstrates
+
+| Feature | Where |
+|---|---|
+| Fluent head/meta API (`createHead()`) | `app/pages/HomePage.tsx`, `app/pages/BlogPostPage.tsx` |
+| Title template (`%s — …`) | both pages |
+| Open Graph (incl. structured `og:image`) | both pages |
+| Twitter card | both pages |
+| JSON-LD structured data | both pages |
+| Canonical + robots | HomePage |
+| Data-driven head from the loader (`handle → head`) | BlogPostPage |
+| Static-asset import via `@img` alias | `HomePage.tsx` (`import logo from '@img/logo.png'`) |
+| Asset alias config | `stone.config.mjs` (`assets.aliases`) |
+| SSR head serialization | `rendering: 'ssr'` |
+
+## Run
+
+> Requires the monorepo workspace to be installed (`pnpm install` at the root) so the
+> `@stone-js/*` workspace packages resolve.
+
+```bash
+pnpm --filter continuum-showcase dev      # stone dev  — SSR dev server
+pnpm --filter continuum-showcase build    # stone build
+pnpm --filter continuum-showcase preview  # serve the build
+```
+
+## Manual verification checklist
+
+1. `stone dev`, open `/` → view source: `<title>Home — Stone.js Showcase</title>`, `og:*`,
+   `twitter:*` and a `<script type="application/ld+json">` are present in the SSR HTML.
+2. The `@img/logo.png` import resolves (no build error) and the logo renders.
+3. `/blog/hello-world` → head reflects the post data (`og:type=article`, per-post JSON-LD).
+4. Put an actual `assets/images/logo.png` in place before running.
+
+## Status
+
+Reference example added in the continuum pass. End-to-end build/render still needs a run of
+the CLI toolchain (Vite/browser) to be fully validated — it is correct against the current
+`@stone-js/use-view` / `@stone-js/use-react` / `@stone-js/cli` APIs.

package/continuum-showcase/app/env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Ambient module declarations so component imports of static assets type-check.
+ * The actual resolution is done by the CLI's Vite `resolve.alias` (see stone.config.mjs).
+ */
+declare module '*.png' {
+  const src: string
+  export default src
+}
+declare module '*.jpg' {
+  const src: string
+  export default src
+}
+declare module '*.svg' {
+  const src: string
+  export default src
+}
+declare module '*.webp' {
+  const src: string
+  export default src
+}
+
+// Asset alias namespaces (mirror stone.config.mjs `assets.aliases`).
+declare module '@img/*' {
+  const src: string
+  export default src
+}
+declare module '@assets/*' {
+  const src: string
+  export default src
+}
+declare module '@css/*' {
+  const href: string
+  export default href
+}

package/continuum-showcase/app/layouts/MainLayout.tsx

@@ -0,0 +1,20 @@
+import React from 'react'
+import { PageLayout } from '@stone-js/router'
+import { IPageLayout, PageLayoutRenderContext } from '@stone-js/use-react'
+
+/**
+ * The default layout. In a future iteration (hierarchical heads), a layout may also
+ * contribute a base head via `createHead().merge(...)`.
+ */
+@PageLayout({ name: 'default' })
+export class MainLayout implements IPageLayout {
+  render ({ children }: PageLayoutRenderContext) {
+    return (
+      <div className="app">
+        <header><nav><a href="/">Home</a> · <a href="/blog/hello-world">Blog</a></nav></header>
+        {children}
+        <footer>◆ Stone.js — the continuum framework</footer>
+      </div>
+    )
+  }
+}

package/continuum-showcase/app/pages/BlogPostPage.tsx

@@ -0,0 +1,62 @@
+import React from 'react'
+import { Page } from '@stone-js/router'
+import {
+  createHead,
+  IPage,
+  PageRenderContext,
+  PageHeadContext,
+  ReactIncomingEvent
+} from '@stone-js/use-react'
+
+interface Post {
+  slug: string
+  title: string
+  excerpt: string
+  cover: string
+  body: string
+}
+
+/**
+ * Blog post page — demonstrates a fully dynamic, data-driven head built from the
+ * loader (`handle`) output, including an `article` Open Graph type and per-post JSON-LD.
+ */
+@Page({ path: '/blog/:slug' })
+export class BlogPostPage implements IPage<ReactIncomingEvent> {
+  handle (event: ReactIncomingEvent): Post {
+    const slug = event.get<string>('slug', 'hello-world')
+    return {
+      slug,
+      title: 'Hello, Continuum',
+      excerpt: 'How Stone.js applies context to your domain at runtime.',
+      cover: `https://showcase.stonejs.dev/covers/${slug}.png`,
+      body: 'Full article content…'
+    }
+  }
+
+  head ({ data }: PageHeadContext<Post>) {
+    const post = data as Post
+    return createHead()
+      .title(post.title)
+      .titleTemplate('%s — Stone.js Blog')
+      .description(post.excerpt)
+      .canonical(`https://showcase.stonejs.dev/blog/${post.slug}`)
+      .og({ type: 'article', image: post.cover, siteName: 'Stone.js Blog' })
+      .twitter({ card: 'summary_large_image', site: '@stonejs' })
+      .jsonLd({
+        '@context': 'https://schema.org',
+        '@type': 'Article',
+        headline: post.title,
+        description: post.excerpt
+      })
+      .toContext()
+  }
+
+  render ({ data }: PageRenderContext<Post>) {
+    return (
+      <article>
+        <h1>{data?.title}</h1>
+        <p>{data?.body}</p>
+      </article>
+    )
+  }
+}

package/continuum-showcase/app/pages/HomePage.tsx

@@ -0,0 +1,58 @@
+import React from 'react'
+import { Page } from '@stone-js/router'
+import logo from '@img/logo.png'
+import {
+  createHead,
+  IPage,
+  PageRenderContext,
+  ReactIncomingEvent
+} from '@stone-js/use-react'
+
+interface HomeData {
+  message: string
+}
+
+/**
+ * Home page — demonstrates:
+ *  - the fluent head/meta API (title template, description, canonical, Open Graph,
+ *    Twitter card and JSON-LD structured data), all from `head()`;
+ *  - importing a static asset via the `@img` alias (resolved by the CLI's Vite config).
+ */
+@Page({ path: '/' })
+export class HomePage implements IPage<ReactIncomingEvent> {
+  handle (): HomeData {
+    return { message: 'Write your domain once. Stone.js applies the context.' }
+  }
+
+  head () {
+    return createHead()
+      .title('Home')
+      .titleTemplate('%s — Stone.js Showcase')
+      .description('A Continuum Architecture showcase: universal pages, SSR head, static assets.')
+      .canonical('https://showcase.stonejs.dev/')
+      .og({
+        type: 'website',
+        siteName: 'Stone.js Showcase',
+        image: { url: 'https://showcase.stonejs.dev/og.png', width: 1200, height: 630, alt: 'Stone.js' }
+      })
+      .twitter({ card: 'summary_large_image', site: '@stonejs' })
+      .robots({ index: true, follow: true })
+      .jsonLd({
+        '@context': 'https://schema.org',
+        '@type': 'WebSite',
+        name: 'Stone.js Showcase',
+        url: 'https://showcase.stonejs.dev/'
+      })
+      .toContext()
+  }
+
+  render ({ data }: PageRenderContext<HomeData>) {
+    return (
+      <main>
+        <img src={logo} alt="Stone.js" width={96} height={96} />
+        <h1>Stone.js Showcase</h1>
+        <p>{data?.message}</p>
+      </main>
+    )
+  }
+}

package/continuum-showcase/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "continuum-showcase",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Showcase app exercising the new head/OG API and static-asset aliases (2026-07 continuum pass).",
+  "scripts": {
+    "dev": "stone dev",
+    "build": "stone build",
+    "preview": "stone preview"
+  },
+  "dependencies": {
+    "@stone-js/browser-adapter": "^0.8.3",
+    "@stone-js/core": "^0.8.3",
+    "@stone-js/node-http-adapter": "^0.8.3",
+    "@stone-js/router": "^0.8.3",
+    "@stone-js/use-react": "^0.8.3",
+    "@stone-js/use-view": "^0.8.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@stone-js/cli": "^0.8.3"
+  }
+}

package/continuum-showcase/stone.config.mjs

@@ -0,0 +1,20 @@
+import { defineConfig } from '@stone-js/cli'
+
+/**
+ * Build configuration for the showcase.
+ *
+ * - `target: 'react'` + `rendering: 'ssr'` exercises the server-rendered head pipeline.
+ * - `assets` enables the `@img` / `@css` / `@assets` import aliases used in components.
+ */
+export default defineConfig({
+  target: 'react',
+  rendering: 'ssr',
+  assets: {
+    dir: 'assets',
+    aliases: {
+      '@assets': '',
+      '@img': 'images',
+      '@css': 'css'
+    }
+  }
+})

package/full-react-declarative/.env.example

@@ -0,0 +1 @@
+BASE_URL=http://localhost:3100

package/full-react-declarative/.env.public.example

@@ -0,0 +1 @@
+API_BASE_URL=http://localhost:8080

package/full-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/full-react-declarative/README.md

@@ -0,0 +1,39 @@
+# Stone.js - Full starter
+
+Stone.js's full starter to create web 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/full-react-declarative/app/Application.ts

@@ -0,0 +1,85 @@
+import { Routing } from '@stone-js/router'
+import { Browser } from '@stone-js/browser-adapter'
+import { Hook, UseReact } from '@stone-js/use-react'
+import { NodeHttp } from '@stone-js/node-http-adapter'
+import { NodeConsole } from '@stone-js/node-cli-adapter'
+import { IBlueprint, IContainer, ILogger, LogLevel, Promiseable, StoneApp } from '@stone-js/core'
+
+/**
+ * Application
+ *
+ * This is the main application entry point.
+ *
+ * @StoneApp() is used to enable the Stone application, it is mandatory.
+ * @Routing() is used to enable the routing feature.
+ * @NodeHttp() is used to enable the Node HTTP adapter.
+ * @NodeConsole() is used to enable the Node Console adapter.
+ * @NodeConsole() requires the incoming event type.
+ * BodyEventMiddleware is used to parse the incoming event body.
+ * BodyEventMiddleware is imported because it is not installed by default.
+ *
+ * You have access to the Stone's application lifecycle hooks.
+ * You can also have access to them in the ServiceProviders.
+ * They are optional and you can remove them if you don't need them.
+ */
+@Routing()
+@Browser()
+@UseReact()
+@NodeConsole()
+@NodeHttp({ default: true, url: 'http://localhost:3100' })
+@StoneApp({ name: 'My Stone', logger: { level: LogLevel.DEBUG } })
+export class Application {
+  /**
+   * Start the application
+   * Run at each cold start.
+   * At this point, you only have access to the blueprint.
+   * Because the container is not yet created.
+   */
+  @Hook('onStart')
+  onStart ({ blueprint }: { blueprint: IBlueprint }): void {
+    const AppName = blueprint.get<string>('stone.name')
+    console.log(`${String(AppName)}'s Application is starting`)
+  }
+
+  /**
+   * Prepare the application
+   * Run at each warm start in server context.
+   * And at each cold start in browser context.
+   */
+  @Hook('onInit')
+  onInit ({ logger }: { logger: ILogger }): Promiseable<void> {
+    logger.info('Application is initializing')
+  }
+
+  /**
+   * Before handle the incoming event
+   */
+  @Hook('onHandlingEvent')
+  onHandlingEvent ({ logger }: { logger: ILogger }): Promiseable<void> {
+    logger.info('Before handle incoming event')
+  }
+
+  /**
+   * Before prepare the react page
+   */
+  @Hook('onPreparingPage')
+  onPreparingPage ({ container }: { container: IContainer }): Promiseable<void> {
+    container.make<ILogger>('logger').info('Before prepare the react page')
+  }
+
+  /**
+   * After the incoming event has been processed
+   */
+  @Hook('onProcessingKernelMiddleware')
+  onProcessingKernelMiddleware ({ pipe }: { pipe: any }): Promiseable<void> {
+    console.info('Kernel middleware is processing', pipe.module.name)
+  }
+
+  /**
+   * After the platform event has been sent to the user
+   */
+  @Hook('onTerminate')
+  onTerminate ({ logger }: { logger: ILogger }): Promiseable<void> {
+    logger.info('The event has been sent to the user')
+  }
+}

package/full-react-declarative/app/clients/AxiosClient.ts

@@ -0,0 +1,136 @@
+import { isEmpty, isNotEmpty } from '@stone-js/core'
+import { TokenService } from '../services/TokenService'
+import { UnauthorizedError } from '../errors/UnauthorizedError'
+import { isServer, ReactIncomingEvent } from '@stone-js/use-react'
+import { AxiosError, Axios, AxiosRequestConfig, AxiosResponse } from 'axios'
+
+/**
+ * Axios Client Options
+ */
+export interface AxiosClientOptions {
+  axios: Axios
+  event: ReactIncomingEvent
+  tokenService: TokenService
+}
+
+/**
+ * Axios Client
+ */
+export class AxiosClient {
+  private readonly axios: Axios
+  private readonly event: ReactIncomingEvent
+  private readonly tokenService: TokenService
+
+  /**
+   * Create a new Axios Client
+   *
+   * @param options - The options to create the Axios Client.
+   */
+  constructor ({ axios, event, tokenService }: AxiosClientOptions) {
+    this.axios = axios
+    this.event = event
+    this.tokenService = tokenService
+  }
+
+  /**
+   * Make a request
+   *
+   * @param url - The URL to request
+   * @param data - The data to send
+   * @param options - The request options
+   * @returns The response data
+   * @throws NotAuthenticateError
+   * @throws AxiosError
+   */
+  async request<T = any, R = AxiosResponse<T>, D = any>(url: string, payload?: D, options?: AxiosRequestConfig<D>): Promise<T> {
+    try {
+      const headers: any = ((options?.headers) != null) || {}
+      const token = await this.getAccessToken()
+      // const validateStatus = (status: number) => status >= 200 && status < 500
+
+      if (isServer()) { headers['User-Agent'] = this.event.userAgent }
+
+      headers.Accept ??= 'application/json'
+      headers['Content-Type'] ??= 'application/json'
+      headers.Authorization = isEmpty(token) ? '' : `Bearer ${token}`
+
+      return (await this.axios.request({ ...options, url, data: payload, headers /* validateStatus */ })).data
+    } catch (error: any) {
+      if (isNotEmpty<AxiosError<R, D>>(error) && error.status === 401) {
+        throw new UnauthorizedError(error.message, { cause: error })
+      } else {
+        throw error
+      }
+    }
+  }
+
+  /**
+   * Make a GET request
+   *
+   * @param url - The URL to request
+   * @param options - The request options
+   * @returns The response data
+   */
+  async get<T = any, R = AxiosResponse<T>, D = any>(url: string, options?: AxiosRequestConfig<D>): Promise<T> {
+    return await this.request<T, R, D>(url, undefined, { ...options, method: 'GET' })
+  }
+
+  /**
+   * Make a POST request
+   *
+   * @param url - The URL to request
+   * @param data - The data to send
+   * @param options - The request options
+   * @returns The response data
+   */
+  async post<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, options?: AxiosRequestConfig<D>): Promise<T> {
+    return await this.request<T, R, D>(url, data, { ...options, method: 'POST' })
+  }
+
+  /**
+   * Make a PUT request
+   *
+   * @param url - The URL to request
+   * @param data - The data to send
+   * @param options - The request options
+   * @returns The response data
+   */
+  async put<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, options?: AxiosRequestConfig<D>): Promise<T> {
+    return await this.request<T, R, D>(url, data, { ...options, method: 'PUT' })
+  }
+
+  /**
+   * Make a PATCH request
+   *
+   * @param url - The URL to request
+   * @param data - The data to send
+   * @param options - The request options
+   * @returns The response data
+   */
+  async patch<T = any, R = AxiosResponse<T>, D = any>(url: string, data?: D, options?: AxiosRequestConfig<D>): Promise<T> {
+    return await this.request<T, R, D>(url, data, { ...options, method: 'PATCH' })
+  }
+
+  /**
+   * Make a DELETE request
+   *
+   * @param url - The URL to request
+   * @param options - The request options
+   * @returns The response data
+   */
+  async delete<T = any, R = AxiosResponse<T>, D = any>(url: string, options?: AxiosRequestConfig<D>): Promise<T> {
+    return await this.request<T, R, D>(url, undefined, { ...options, method: 'DELETE' })
+  }
+
+  /**
+   * Get the access token
+   *
+   * @returns The access token
+   */
+  private async getAccessToken (): Promise<string> {
+    if (isNotEmpty(this.tokenService.getAccessToken()) && !this.tokenService.isAuthenticated()) {
+      await this.tokenService.refresh()
+    }
+    return this.tokenService.getAccessToken() ?? ''
+  }
+}

package/full-react-declarative/app/clients/CommentClient.ts

@@ -0,0 +1,61 @@
+import { Stone } from '@stone-js/core'
+import { AxiosClient } from './AxiosClient'
+import { Comment, CommentInput } from '../models/Comment'
+
+/**
+ * Comment Client Options
+*/
+export interface CommentClientOptions {
+  httpClient: AxiosClient
+}
+
+/**
+ * Comment Client
+ */
+@Stone({ alias: 'commentClient' })
+export class CommentClient {
+  private readonly path: string
+  private readonly client: AxiosClient
+
+  /**
+   * Create a new Comment Client
+   *
+   * @param options - The options to create the Comment Client.
+   */
+  constructor ({ httpClient }: CommentClientOptions) {
+    this.path = '/comments'
+    this.client = httpClient
+  }
+
+  /**
+   * List comments
+   *
+   * @param postId - The id of the Post to list Comments
+   * @param limit - The limit of Comments to list
+   * @returns The list of Comments
+   */
+  async list (postId: number, limit: number = 10): Promise<Comment[]> {
+    const query = new URLSearchParams({ limit: limit.toString() })
+    return await this.client.get<Comment[]>(`${this.path}/posts/${postId}?${String(query)}`)
+  }
+
+  /**
+   * Create a comment
+   *
+   * @param postId - The id of the Post to create the Comment for
+   * @param comment - The Comment to create
+   * @returns The created Comment
+   */
+  async create (postId: number, comment: CommentInput): Promise<Comment> {
+    return await this.client.post(`${this.path}/posts/${postId}`, { ...comment, id: undefined })
+  }
+
+  /**
+   * Delete a comment
+   *
+   * @param id - The id of the Comment to delete
+   */
+  async delete (id: number): Promise<unknown> {
+    return await this.client.delete(`${this.path}/${id}`)
+  }
+}