@starci/hfs 1.0.1 → 2.0.0

package/templates/be/skeleton/src/modules/platform/logging/index.ts

@@ -1,5 +1,5 @@
-export { createJsonLogger } from "./json-logger"
-export { LogId } from "./log-id"
-export { Logger } from "./logger.port"
-export type { LogPayload } from "./logger.port"
+export { createJsonLogger } from "./json-logger.service"
+export { InjectLogger } from "./logging.decorators"
+export { LoggingLogEvent } from "./logging.log-events"
 export { LoggingModule } from "./logging.module"
+export type { Logger } from "./logging.port"

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.spec.ts

@@ -0,0 +1,99 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { JsonLoggerService, createJsonLogger } from "./json-logger.service"
+
+const TIME = "2026-01-01T00:00:00.000Z"
+
+const build = async () => {
+    const clock = new FakeClock(TIME)
+    const moduleRef = await Test.createTestingModule({
+        providers: [JsonLoggerService, { provide: CLOCK, useValue: clock }],
+    }).compile()
+    return { service: moduleRef.get(JsonLoggerService), clock }
+}
+
+/** One JSON line, the way the logger writes it. */
+const line = (fields: Record<string, unknown>): string => `${JSON.stringify(fields)}\n`
+
+describe("JsonLoggerService", () => {
+    const stdout: Array<string> = []
+    const stderr: Array<string> = []
+
+    beforeEach(() => {
+        stdout.length = 0
+        stderr.length = 0
+        jest.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+            stdout.push(String(chunk))
+            return true
+        })
+        jest.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+            stderr.push(String(chunk))
+            return true
+        })
+    })
+
+    afterEach(() => {
+        jest.restoreAllMocks()
+    })
+
+    describe("info", () => {
+        it("stamps the line with the clock and writes it to stdout", async () => {
+            const { service } = await build()
+
+            service.info("thing.happened", { id: 1 })
+
+            expect(stdout).toEqual([line({ level: "info", event: "thing.happened", time: TIME, id: 1 })])
+            expect(stderr).toEqual([])
+        })
+    })
+
+    describe("warn", () => {
+        it("writes the line to stderr, stamped with the moment of the call", async () => {
+            const { service, clock } = await build()
+            clock.advance(5_000)
+
+            service.warn("thing.slow")
+
+            expect(stderr).toEqual([line({ level: "warn", event: "thing.slow", time: "2026-01-01T00:00:05.000Z" })])
+            expect(stdout).toEqual([])
+        })
+    })
+
+    describe("error", () => {
+        it("serializes an Error cause by name and message", async () => {
+            const { service } = await build()
+
+            service.error("thing.failed", new TypeError("boom"), { id: 2 })
+
+            expect(stderr).toEqual([
+                line({
+                    level: "error",
+                    event: "thing.failed",
+                    time: TIME,
+                    errorName: "TypeError",
+                    errorMessage: "boom",
+                    id: 2,
+                }),
+            ])
+        })
+
+        it("serializes a cause that is not an Error to its text", async () => {
+            const { service } = await build()
+
+            service.error("thing.failed", "plain text")
+
+            expect(stderr).toEqual([
+                line({ level: "error", event: "thing.failed", time: TIME, errorMessage: "plain text" }),
+            ])
+        })
+    })
+
+    describe("createJsonLogger", () => {
+        it("builds a logger stamped by the given clock", () => {
+            createJsonLogger(new FakeClock(TIME)).info("thing.started")
+
+            expect(stdout).toEqual([line({ level: "info", event: "thing.started", time: TIME })])
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.ts

@@ -0,0 +1,38 @@
+import { Injectable } from "@nestjs/common"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import type { LogFields, Logger } from "./logging.port"
+
+type Level = "info" | "warn" | "error"
+
+@Injectable()
+/** The default adapter: one JSON object per line, stamped by the Clock; info goes to stdout, warn and error to stderr. */
+export class JsonLoggerService implements Logger {
+    constructor(@InjectClock() private readonly clock: Clock) {}
+
+    /** Writes an info line. */
+    info(event: string, fields?: LogFields): void {
+        this.write("info", process.stdout, event, fields)
+    }
+
+    /** Writes a warn line. */
+    warn(event: string, fields?: LogFields): void {
+        this.write("warn", process.stderr, event, fields)
+    }
+
+    /** Writes an error line with the cause serialized by name and message. */
+    error(event: string, cause: unknown, fields?: LogFields): void {
+        const detail =
+            cause instanceof Error
+                ? { errorName: cause.name, errorMessage: cause.message }
+                : { errorMessage: String(cause) }
+        this.write("error", process.stderr, event, { ...detail, ...fields })
+    }
+
+    private write(level: Level, sink: NodeJS.WriteStream, event: string, fields?: LogFields): void {
+        sink.write(`${JSON.stringify({ level, event, time: this.clock.now().toISOString(), ...fields })}\n`)
+    }
+}
+
+/** Builds the JSON logger stamping lines with `clock`; main.ts uses it before the DI container exists. */
+export const createJsonLogger = (clock: Clock): Logger => new JsonLoggerService(clock)

package/templates/be/skeleton/src/modules/platform/logging/logging.decorators.ts

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Logger } from "./logging.port"
+
+/** Token of the Logger port. */
+export const LOGGER: unique symbol = Symbol("platform.logging.logger")
+
+/** Injects the Logger port. Parameter type: Logger. */
+export const InjectLogger = (): TypedParameterDecorator<Logger> => injector<Logger>(LOGGER)

package/templates/be/skeleton/src/modules/platform/logging/logging.log-events.ts

@@ -0,0 +1,7 @@
+/** Log events of the process lifecycle: the entry points (main.ts of each app) log these. */
+export enum LoggingLogEvent {
+    /** The HTTP listener is bound and the service answers requests. */
+    ServerStarted = "server.started",
+    /** The service failed before it could serve; the process exits non-zero. */
+    StartupFailed = "server.startup_failed",
+}

package/templates/be/skeleton/src/modules/platform/logging/logging.module-definition.ts

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { LoggingOptions } from "./logging.options"
+
+/** The configurable-module base of the logging capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<LoggingOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/skeleton/src/modules/platform/logging/logging.module.ts

@@ -1,11 +1,24 @@
-import { Global, Module } from "@nestjs/common"
-import { createJsonLogger } from "./json-logger"
-import { Logger } from "./logger.port"
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { CLOCK } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { createJsonLogger } from "./json-logger.service"
+import { LOGGER } from "./logging.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./logging.module-definition"
 
-/** Provides the logging port to every capability; one of the three platform modules that may be global. */
-@Global()
-@Module({
-    providers: [{ provide: Logger, useFactory: (): Logger => createJsonLogger() }],
-    exports: [Logger],
-})
-export class LoggingModule {}
+@Module({})
+/** Provides the Logger port as the JSON-lines adapter stamped by the Clock the app registers. */
+export class LoggingModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [
+                ...(base.providers ?? []),
+                { provide: LOGGER, inject: [CLOCK], useFactory: (clock: Clock) => createJsonLogger(clock) },
+            ],
+            exports: [LOGGER],
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/logging/logging.options.ts

@@ -0,0 +1,2 @@
+/** The logging capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type LoggingOptions = Record<never, never>

package/templates/be/skeleton/src/modules/platform/logging/logging.port.ts

@@ -0,0 +1,15 @@
+/** The structured data of one log line; values are plain data, never a request, a token or a secret. */
+export interface LogFields {
+    /** The value logged under `name`. */
+    readonly [name: string]: unknown
+}
+
+/** The logging port: owners log through it with an enum member of their own `<owner>.log-events.ts`, never `console`. */
+export interface Logger {
+    /** A normal event worth keeping. */
+    info(event: string, fields?: LogFields): void
+    /** Something unexpected the service recovered from. */
+    warn(event: string, fields?: LogFields): void
+    /** A failure: the cause is serialized by name and message, never dumped whole. */
+    error(event: string, cause: unknown, fields?: LogFields): void
+}

package/templates/be/tool-config/eslint.config.mjs

@@ -0,0 +1,3 @@
+import { loadHfs, starciBeConfig } from "@starci/eslint-canon-be"
+
+export default starciBeConfig({ hfs: loadHfs(import.meta.url) })

package/templates/be/tool-config/jest.config.js

@@ -0,0 +1 @@
+module.exports = require("@starci/jest-preset").starciJestConfig()

package/templates/be/tool-config/prettierignore

@@ -0,0 +1,8 @@
+{{header}}
+dist/
+coverage/
+node_modules/
+package-lock.json
+contracts/
+.starcistacks/
+.starciwork/

package/templates/be/tool-config/prettierrc

@@ -0,0 +1 @@
+"@starci/prettier-config"

package/templates/be/tool-config/src/tests/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": ["../../tsconfig.json", "@starci/tsconfig/e2e.json"],
+  "include": ["./**/*.ts"],
+  "exclude": []
+}

package/templates/be/tool-config/tsconfig.build.json

@@ -0,0 +1,5 @@
+{
+  "extends": ["./tsconfig.json", "@starci/tsconfig/build.json"],
+  "compilerOptions": { "outDir": "./dist" },
+  "exclude": ["node_modules", "dist", "**/*.spec.ts", "src/tests"]
+}

package/templates/be/tool-config/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@starci/tsconfig/be.json",
+  "compilerOptions": {
+    "paths": {
+      "@features/*": ["./src/features/*"],
+      "@modules/*": ["./src/modules/*"],
+      "@tests/*": ["./src/tests/*"]
+    }
+  },
+  "exclude": ["node_modules", "dist", "src/tests/world", "src/tests/integration", "src/tests/e2e", "src/tests/contract"]
+}

package/templates/common/gitignore.base

@@ -2,8 +2,8 @@
 node_modules/
 dist/
 coverage/
+reports/
 test-results/
-playwright-report/
 *.tsbuildinfo
 .scannerwork/
 .turbo/

package/templates/fe/ci-workflows/github/workflows/ci.yml

@@ -0,0 +1,54 @@
+{{header}}
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    env:
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: {{nodeMajor}}
+          cache: npm
+      - run: npm ci
+      - name: hfs check
+        run: npm run hfs:report
+      - name: lint
+        run: npm run lint:check
+      - name: eslint report
+        if: ${{ !cancelled() }}
+        run: npm run lint:report
+      - name: eslint sonar import
+        if: ${{ !cancelled() }}
+        run: npx hfs report eslint reports/eslint.json reports/eslint.sonar.json
+      - name: stylelint report
+        if: ${{ !cancelled() }}
+        run: npm run lint:report:css
+      - name: stylelint sonar import
+        if: ${{ !cancelled() }}
+        run: npx hfs report stylelint reports/stylelint.json reports/stylelint.sonar.json
+      - name: format
+        run: npm run format:check
+      - name: typecheck
+        run: npm run typecheck
+      - name: build
+        run: npm run build
+      - uses: SonarSource/sonarqube-scan-action@v7
+        if: ${{ !cancelled() && env.SONAR_TOKEN != '' }}
+        env:
+          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
+      - uses: SonarSource/sonarqube-quality-gate-action@v1
+        if: ${{ !cancelled() && env.SONAR_TOKEN != '' }}
+        timeout-minutes: 10
+        env:
+          SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}

package/templates/fe/hooks/husky/pre-commit

@@ -0,0 +1,16 @@
+{{header}}
+# Commit gate: the secrets guard, then types, lint and format of the staged files.
+npx hfs work-hygiene
+npm run typecheck
+sources=$(git diff --cached --name-only --diff-filter=ACMR -- '*.ts' '*.tsx' '*.mts' '*.cts' '*.js' '*.jsx' '*.mjs' '*.cjs' || true)
+if [ -n "$sources" ]; then
+  npx eslint --max-warnings=0 --no-warn-ignored $sources
+fi
+styles=$(git diff --cached --name-only --diff-filter=ACMR -- '*.css' || true)
+if [ -n "$styles" ]; then
+  npx stylelint $styles
+fi
+formatted=$(git diff --cached --name-only --diff-filter=ACMR || true)
+if [ -n "$formatted" ]; then
+  npx prettier --check --ignore-unknown $formatted
+fi

package/templates/fe/hooks/husky/pre-push

@@ -0,0 +1,6 @@
+{{header}}
+# Push gate: types, lint (eslint over the repository, stylelint over the CSS), format, the architecture check on the owners this push touches.
+npm run typecheck
+npm run lint:check
+npm run format:check
+npm run hfs:check -- --fast

package/templates/fe/package-scripts/package.json

@@ -0,0 +1,17 @@
+{
+  "scripts": {
+    "prepare": "husky",
+    {{appScripts}}
+    "codegen": "npm run codegen --workspaces --if-present",
+    "build": "npm run build --workspaces --if-present",
+    "typecheck": "npm run typecheck --workspaces --if-present",
+    "lint": "npm run codegen --silent && eslint . --fix --max-warnings=0 && stylelint \"{{styleGlob}}\" --fix",
+    "lint:check": "npm run codegen --silent && eslint . --max-warnings=0 && stylelint \"{{styleGlob}}\"",
+    "lint:report": "eslint . --format json --output-file reports/eslint.json",
+    "lint:report:css": "stylelint \"{{styleGlob}}\" --formatter json --output-file reports/stylelint.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "hfs:check": "hfs check",
+    "hfs:report": "hfs check --sonar reports/hfs.sonar.json"
+  }
+}

package/templates/fe/parts/api-client.ts

@@ -0,0 +1,44 @@
+import type { Outcome } from "./outcome"
+
+/** How long a request waits before it is abandoned and answered `unavailable`. */
+const REQUEST_TIMEOUT_MS = 8000
+
+/** One request of the client: the caller's own signal is joined with the timeout. */
+export interface ClientRequest {
+    readonly url: string
+    readonly method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+    readonly body?: unknown
+    readonly signal?: AbortSignal
+}
+
+/** The status of a response as an Outcome kind; 401 and 403 are `refused`, nothing collapses into `null`. */
+const toOutcome = async (response: Response): Promise<Outcome<unknown>> => {
+    if (response.status === 401 || response.status === 403) return { kind: "refused" }
+    if (response.status === 404) return { kind: "not-found" }
+    if (response.status === 400 || response.status === 422) return { kind: "invalid" }
+    if (!response.ok) return { kind: "unavailable" }
+    try {
+        return { kind: "ok", data: (await response.json()) as unknown }
+    } catch {
+        return { kind: "unavailable" }
+    }
+}
+
+/**
+ * The repository's one fetch. It always carries a timeout signal, never throws, and answers an Outcome; the body is
+ * `unknown` until a generated wire type narrows it.
+ */
+export const request = async ({ url, method = "GET", body, signal }: ClientRequest): Promise<Outcome<unknown>> => {
+    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    try {
+        const response = await fetch(url, {
+            method,
+            headers: { accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json" }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+        })
+        return await toOutcome(response)
+    } catch {
+        return { kind: "unavailable" }
+    }
+}

package/templates/fe/parts/api-outcome.ts

@@ -0,0 +1,7 @@
+/** The one result every read of the backend returns: a status is a kind, never a thrown error and never `null`. */
+export type Outcome<T> =
+    | { readonly kind: "ok"; readonly data: T }
+    | { readonly kind: "refused" }
+    | { readonly kind: "invalid" }
+    | { readonly kind: "not-found" }
+    | { readonly kind: "unavailable" }

package/templates/fe/quality-config/sonar-project.properties

@@ -0,0 +1,8 @@
+{{header}}
+sonar.projectKey={{sonarKey}}
+sonar.sourceEncoding=UTF-8
+sonar.sources={{sonarRoots}}
+sonar.exclusions=**/.next/**,**/node_modules/**,**/src/messages/**
+sonar.typescript.tsconfigPaths={{tsconfigPaths}}
+sonar.externalIssuesReportPaths=reports/hfs.sonar.json,reports/eslint.sonar.json,reports/stylelint.sonar.json
+sonar.nodejs.maxspace=8192

package/templates/fe/skeleton/apps/__app__/src/app/[locale]/layout.tsx

@@ -2,7 +2,7 @@ import { hasLocale, NextIntlClientProvider } from "next-intl"
 import { getMessages, setRequestLocale } from "next-intl/server"
 import { notFound } from "next/navigation"
 import type { ReactNode } from "react"
-import { routing } from "../../modules/i18n/routing"
+import { routing } from "../../modules/i18n"
 import "../globals.css"
 
 interface LocaleLayoutProps {

package/templates/fe/skeleton/apps/__app__/src/app/[locale]/not-found.tsx

@@ -1,5 +1,5 @@
 import { getTranslations } from "next-intl/server"
-import { Link } from "../../modules/i18n/navigation"
+import { Link } from "../../modules/i18n"
 
 /** Shown when a route calls `notFound()`. */
 const NotFound = async () => {

package/templates/fe/skeleton/apps/__app__/src/app/global-error.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import { DEFAULT_LOCALE } from "../modules/i18n/config"
+import { DEFAULT_LOCALE } from "../modules/i18n"
 import messages from "../modules/i18n/messages/vi.json"
 
 interface GlobalErrorProps {

package/templates/fe/skeleton-app/apps/__app__/src/modules/api/client.ts

@@ -0,0 +1 @@
+{{> fe/parts/api-client.ts}}

package/templates/fe/skeleton-app/apps/__app__/src/modules/api/index.ts

@@ -0,0 +1,3 @@
+export { request } from "./client"
+export type { ClientRequest } from "./client"
+export type { Outcome } from "./outcome"

package/templates/fe/skeleton-app/apps/__app__/src/modules/api/outcome.ts

@@ -0,0 +1 @@
+{{> fe/parts/api-outcome.ts}}

package/templates/fe/skeleton-app/apps/__app__/src/modules/i18n/index.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_LOCALE, LOCALES } from "./config"
+export type { Locale } from "./config"
+export { getPathname, Link, redirect, usePathname, useRouter } from "./navigation"
+export { routing } from "./routing"

package/templates/fe/skeleton-shared/apps/__app__/next.config.ts

@@ -0,0 +1,12 @@
+import type { NextConfig } from "next"
+import createNextIntlPlugin from "next-intl/plugin"
+
+const withNextIntl = createNextIntlPlugin("./src/modules/i18n/request.ts")
+
+/** Next config of the {{app}} app: next-intl wired to the request config, Turbopack rooted at the repository, the shared packages compiled from source. */
+const nextConfig: NextConfig = {
+    turbopack: { root: process.cwd() },
+    transpilePackages: ["@{{family}}/i18n", "@{{family}}/api"],
+}
+
+export default withNextIntl(nextConfig)

package/templates/fe/skeleton-shared/apps/__app__/src/modules/api/index.ts

@@ -0,0 +1,2 @@
+export { request } from "@{{family}}/api"
+export type { ClientRequest, Outcome } from "@{{family}}/api"

package/templates/fe/skeleton-shared/apps/__app__/src/modules/i18n/index.ts

@@ -0,0 +1,9 @@
+import { createAppI18n } from "@{{family}}/i18n"
+
+/** This app's locales and the next-intl stack (routing, navigation) built from them by the shared i18n package. */
+const i18n = createAppI18n({ locales: ["vi"], defaultLocale: "vi" })
+
+export const { DEFAULT_LOCALE, LOCALES, getPathname, Link, redirect, routing, usePathname, useRouter } = i18n
+
+/** A served locale. */
+export type Locale = (typeof LOCALES)[number]

package/templates/fe/skeleton-shared/apps/__app__/src/modules/i18n/request.ts

@@ -0,0 +1,5 @@
+import { createRequestConfig } from "@{{family}}/i18n/request"
+import { routing } from "./index"
+
+/** Loads the catalog of the requested locale from this app's `messages/`; the shared package resolves the locale. */
+export default createRequestConfig(routing, async (locale) => (await import(`./messages/${locale}.json`)).default)

package/templates/fe/skeleton-shared/apps/__app__/src/proxy.ts

@@ -0,0 +1,5 @@
+import { createProxy } from "@{{family}}/i18n/proxy"
+import { routing } from "./modules/i18n"
+
+/** Negotiates the locale and redirects; the default locale (vi) is served without a prefix. */
+export default createProxy(routing)

package/templates/fe/skeleton-shared/packages/__family__-api/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@{{family}}/api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --pretty false"
+  }
+}

package/templates/fe/skeleton-shared/packages/__family__-api/src/client.ts

@@ -0,0 +1 @@
+{{> fe/parts/api-client.ts}}

package/templates/fe/skeleton-shared/packages/__family__-api/src/index.ts

@@ -0,0 +1,3 @@
+export { request } from "./client"
+export type { ClientRequest } from "./client"
+export type { Outcome } from "./outcome"

package/templates/fe/skeleton-shared/packages/__family__-api/src/outcome.ts

@@ -0,0 +1 @@
+{{> fe/parts/api-outcome.ts}}

package/templates/fe/skeleton-shared/packages/__family__-api/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@starci/tsconfig/next.json",
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules"]
+}

package/templates/fe/skeleton-shared/packages/__family__-i18n/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@{{family}}/i18n",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./proxy": "./src/proxy.ts",
+    "./request": "./src/request.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit --pretty false"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "next-intl": ">=4"
+  }
+}

package/templates/fe/skeleton-shared/packages/__family__-i18n/src/app.ts

@@ -0,0 +1,19 @@
+import { createNavigation } from "next-intl/navigation"
+import { defineRouting } from "next-intl/routing"
+
+/** The locales an app serves and the one it serves at the unprefixed path. */
+export interface AppI18nOptions<Locale extends string> {
+    readonly locales: readonly [Locale, ...Locale[]]
+    readonly defaultLocale: Locale
+}
+
+/**
+ * The next-intl stack of one app, written once for the repository: one routing table (default locale unprefixed) and the
+ * locale-aware navigation built on it. Components import `Link` and `redirect` from their app's i18n module, never from
+ * `next/link` or `next/navigation`. The proxy and the request config are the `./proxy` and `./request` entries, so a client
+ * bundle that imports this one carries no server code.
+ */
+export const createAppI18n = <const Locale extends string>({ locales, defaultLocale }: AppI18nOptions<Locale>) => {
+    const routing = defineRouting({ locales, defaultLocale, localePrefix: "as-needed" })
+    return { LOCALES: locales, DEFAULT_LOCALE: defaultLocale, routing, ...createNavigation(routing) }
+}

package/templates/fe/skeleton-shared/packages/__family__-i18n/src/index.ts

@@ -0,0 +1,2 @@
+export { createAppI18n } from "./app"
+export type { AppI18nOptions } from "./app"

package/templates/fe/skeleton-shared/packages/__family__-i18n/src/proxy.ts

@@ -0,0 +1,12 @@
+import createMiddleware from "next-intl/middleware"
+import type { defineRouting } from "next-intl/routing"
+import { NextResponse, type NextRequest } from "next/server"
+
+/** The API, the health probe, framework files and files with an extension are never locale-negotiated. */
+const UNNEGOTIATED = /^\/(?:api|health|_next|_vercel)(?:\/|$)|\.[^/]+$/
+
+/** The proxy of an app: negotiates the locale and redirects, and lets everything that is not a page through untouched. */
+export const createProxy = (routing: ReturnType<typeof defineRouting>) => {
+    const negotiate = createMiddleware(routing)
+    return (request: NextRequest) => (UNNEGOTIATED.test(request.nextUrl.pathname) ? NextResponse.next() : negotiate(request))
+}