create-simone-app 0.1.0

package/templates/fe/base/src/features/users/users.schema.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+
+export const USER_ROLES = ['admin', 'editor', 'viewer'] as const
+export type UserRole = (typeof USER_ROLES)[number]
+
+export const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string(),
+  role: z.enum(USER_ROLES),
+  createdAt: z.string(),
+})
+export type User = z.infer<typeof UserSchema>
+
+/** API list contract shared with simone-api-template. */
+export const UsersResponseSchema = z.object({
+  data: z.array(UserSchema),
+  page: z.number().int(),
+  limit: z.number().int(),
+  total: z.number().int(),
+})
+export type UsersResponse = z.infer<typeof UsersResponseSchema>
+
+export const USER_SORT_FIELDS = ['name', 'email', 'role', 'createdAt'] as const
+export type UserSortField = (typeof USER_SORT_FIELDS)[number]
+
+/** Route search params (tanstack §3.4: table state lives in the URL). */
+export const UsersQuerySchema = z.object({
+  page: z.number().int().min(1).catch(1),
+  limit: z.number().int().min(1).max(100).catch(20),
+  q: z.string().trim().catch(''),
+  sort: z.enum(USER_SORT_FIELDS).catch('name'),
+  order: z.enum(['asc', 'desc']).catch('asc'),
+})
+export type UsersQuery = z.infer<typeof UsersQuerySchema>
+
+export const DEFAULT_USERS_QUERY: UsersQuery = {
+  page: 1,
+  limit: 20,
+  q: '',
+  sort: 'name',
+  order: 'asc',
+}

package/templates/fe/base/src/lib/apiClient.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { ApiError, apiClient } from './apiClient'
+
+const originalAdapter = apiClient.defaults.adapter
+
+/** Adapter that fails like axios does (duck-typed AxiosError: no axios import outside apiClient.ts). */
+const failWith = (status: number, data: unknown): void => {
+  apiClient.defaults.adapter = async (config) => {
+    throw Object.assign(
+      new Error(`Request failed with status code ${status}`),
+      {
+        isAxiosError: true,
+        config,
+        response: { data, status, statusText: '', headers: {}, config },
+      },
+    )
+  }
+}
+
+describe('apiClient response interceptor', () => {
+  afterEach(() => {
+    apiClient.defaults.adapter = originalAdapter
+  })
+
+  it('maps the API error body to ApiError', async () => {
+    failWith(404, { error: 'User 42 not found', details: [{ path: 'id' }] })
+    const error = await apiClient.get('/users/42').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ApiError)
+    expect(error).toMatchObject({
+      status: 404,
+      message: 'User 42 not found',
+      details: [{ path: 'id' }],
+    })
+  })
+
+  it('falls back to the axios message when the body has no error field', async () => {
+    failWith(502, 'gateway down')
+    const error = await apiClient.get('/users').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(ApiError)
+    expect((error as ApiError).status).toBe(502)
+    expect((error as ApiError).message).toMatch(/502/)
+  })
+
+  it('passes non-axios errors through untouched', async () => {
+    apiClient.defaults.adapter = async () => {
+      throw new TypeError('boom')
+    }
+    const error = await apiClient.get('/users').catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(TypeError)
+  })
+
+  it('uses the env base url', () => {
+    expect(apiClient.defaults.baseURL).toBe('/api')
+  })
+})

package/templates/fe/base/src/lib/apiClient.ts

@@ -0,0 +1,42 @@
+import axios, { isAxiosError } from 'axios'
+
+import { env } from '@/lib/env'
+
+/** Normalised HTTP error: the API's `{ error, details? }` shape becomes message/details. */
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly details?: unknown,
+  ) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
+interface ErrorBody {
+  error?: string
+  details?: unknown
+}
+
+// core-rules §8.1: single axios instance; nothing else imports axios (enforced by ESLint).
+export const apiClient = axios.create({
+  baseURL: env.apiBaseUrl,
+  timeout: 30_000,
+  headers: { 'Content-Type': 'application/json' },
+})
+
+apiClient.interceptors.response.use(
+  (response) => response,
+  (error: unknown) => {
+    if (!isAxiosError(error)) return Promise.reject(error)
+    const body = error.response?.data as ErrorBody | undefined
+    return Promise.reject(
+      new ApiError(
+        error.response?.status ?? 0,
+        body?.error ?? error.message,
+        body?.details,
+      ),
+    )
+  },
+)

package/templates/fe/base/src/lib/appName.ts

@@ -0,0 +1,2 @@
+/** Project name, substituted once by create-simone-app. Use in template strings so line width never depends on it. */
+export const APP_NAME = '__NAME__'

package/templates/fe/base/src/lib/env.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseEnv } from './env'
+
+describe('parseEnv', () => {
+  it('defaults VITE_API_BASE_URL to /api', () => {
+    expect(parseEnv({})).toEqual({ apiBaseUrl: '/api' })
+  })
+
+  it('reads the configured base url', () => {
+    expect(
+      parseEnv({ VITE_API_BASE_URL: 'https://api.example.test' }).apiBaseUrl,
+    ).toBe('https://api.example.test')
+  })
+
+  it('fails fast on an empty value', () => {
+    expect(() => parseEnv({ VITE_API_BASE_URL: '' })).toThrow(
+      /VITE_API_BASE_URL/,
+    )
+  })
+})

package/templates/fe/base/src/lib/env.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+
+const EnvSchema = z.object({
+  VITE_API_BASE_URL: z
+    .string()
+    .min(1, 'VITE_API_BASE_URL must not be empty')
+    .default('/api'),
+})
+
+export interface Env {
+  apiBaseUrl: string
+}
+
+/** Fail fast: an invalid env throws at module load instead of producing broken requests later. */
+export const parseEnv = (raw: Record<string, unknown>): Env => {
+  const result = EnvSchema.safeParse(raw)
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `${i.path.join('.')}: ${i.message}`)
+      .join('; ')
+    throw new Error(`Invalid environment: ${issues}`)
+  }
+  return { apiBaseUrl: result.data.VITE_API_BASE_URL }
+}
+
+export const env: Env = parseEnv(import.meta.env)

package/templates/fe/base/src/lib/queryClient.ts

@@ -0,0 +1,15 @@
+import { QueryClient } from '@tanstack/react-query'
+
+import { ApiError } from '@/lib/apiClient'
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60_000,
+      // 4xx will not heal on retry; only retry network/5xx once.
+      retry: (failureCount, error) =>
+        failureCount < 1 &&
+        !(error instanceof ApiError && error.status > 0 && error.status < 500),
+    },
+  },
+})

package/templates/fe/base/src/lib/router.ts

@@ -0,0 +1,11 @@
+import { createRouter } from '@tanstack/react-router'
+
+import { routeTree } from '@/routeTree.gen'
+
+export const router = createRouter({ routeTree, defaultPreload: 'intent' })
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}

package/templates/fe/base/src/main.tsx

@@ -0,0 +1,21 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+import { QueryClientProvider } from '@tanstack/react-query'
+import { RouterProvider } from '@tanstack/react-router'
+
+import { queryClient } from '@/lib/queryClient'
+import { router } from '@/lib/router'
+
+import './index.css'
+
+const root = document.getElementById('root')
+if (!root) throw new Error('#root not found')
+
+createRoot(root).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  </StrictMode>,
+)

package/templates/fe/base/src/routeTree.gen.ts

@@ -0,0 +1,77 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as UsersIndexRouteImport } from './routes/users/index'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const UsersIndexRoute = UsersIndexRouteImport.update({
+  id: '/users/',
+  path: '/users/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/users/': typeof UsersIndexRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/users': typeof UsersIndexRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/users/': typeof UsersIndexRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/users/'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/users'
+  id: '__root__' | '/' | '/users/'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  UsersIndexRoute: typeof UsersIndexRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/users/': {
+      id: '/users/'
+      path: '/users'
+      fullPath: '/users/'
+      preLoaderRoute: typeof UsersIndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  UsersIndexRoute: UsersIndexRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()

package/templates/fe/base/src/routes/__root.tsx

@@ -0,0 +1,83 @@
+import { useEffect } from 'react'
+
+import {
+  HeadContent,
+  Link,
+  Outlet,
+  createRootRoute,
+} from '@tanstack/react-router'
+
+import { Moon, Sun } from 'lucide-react'
+
+import { Button } from '@/components/ui/button'
+import { APP_NAME } from '@/lib/appName'
+import { useTheme } from '@/stores'
+
+export const Route = createRootRoute({
+  head: () => ({ meta: [{ title: APP_NAME }] }),
+  component: RootLayout,
+})
+
+function RootLayout() {
+  const { theme, setTheme } = useTheme()
+
+  useEffect(() => {
+    document.documentElement.classList.toggle('dark', theme === 'dark')
+  }, [theme])
+
+  return (
+    <>
+      <HeadContent />
+      {/* a11y §4.1: skip link is the first focusable element */}
+      <a
+        href="#main"
+        className="sr-only focus:not-sr-only focus:fixed focus:top-2 focus:left-2 focus:z-50 focus:rounded focus:bg-background focus:px-4 focus:py-2 focus:text-foreground focus:outline-2 focus:outline-offset-2 focus:outline-ring"
+        data-testid="skip-link"
+      >
+        Salta al contenuto principale
+      </a>
+      <header className="border-b">
+        <nav
+          aria-label="Principale"
+          className="mx-auto flex max-w-5xl items-center gap-6 px-4 py-3"
+          data-testid="nav-main"
+        >
+          <Link to="/" className="font-semibold" data-testid="nav-home-link">
+            {APP_NAME}
+          </Link>
+          <Link
+            to="/users"
+            className="text-muted-foreground hover:text-foreground [&.active]:text-foreground"
+            data-testid="nav-users-link"
+          >
+            Utenti
+          </Link>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            className="ml-auto"
+            aria-label={
+              theme === 'dark' ? 'Attiva tema chiaro' : 'Attiva tema scuro'
+            }
+            aria-pressed={theme === 'dark'}
+            onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
+            data-testid="nav-theme-button"
+          >
+            {theme === 'dark' ? (
+              <Sun aria-hidden="true" />
+            ) : (
+              <Moon aria-hidden="true" />
+            )}
+          </Button>
+        </nav>
+      </header>
+      <main
+        id="main"
+        tabIndex={-1}
+        className="mx-auto max-w-5xl px-4 py-8 outline-none"
+      >
+        <Outlet />
+      </main>
+    </>
+  )
+}

package/templates/fe/base/src/routes/index.tsx

@@ -0,0 +1,26 @@
+import { Link, createFileRoute } from '@tanstack/react-router'
+
+import { APP_NAME } from '@/lib/appName'
+
+export const Route = createFileRoute('/')({
+  head: () => ({ meta: [{ title: `Home — ${APP_NAME}` }] }),
+  component: HomePage,
+})
+
+function HomePage() {
+  return (
+    <section data-testid="home-page">
+      <h1 className="text-2xl font-semibold">{APP_NAME}</h1>
+      <p className="mt-2 text-muted-foreground">
+        Template React 19 + TanStack + Tailwind v4 + shadcn (Base UI).
+      </p>
+      <Link
+        to="/users"
+        className="mt-4 inline-block underline"
+        data-testid="home-users-link"
+      >
+        Vai agli utenti
+      </Link>
+    </section>
+  )
+}

package/templates/fe/base/src/routes/users/index.tsx

@@ -0,0 +1,24 @@
+import {
+  type SearchSchemaInput,
+  createFileRoute,
+  stripSearchParams,
+} from '@tanstack/react-router'
+
+import { UsersPage } from '@/features/users/UsersPage'
+import {
+  DEFAULT_USERS_QUERY,
+  type UsersQuery,
+  UsersQuerySchema,
+} from '@/features/users/users.schema'
+import { APP_NAME } from '@/lib/appName'
+
+export const Route = createFileRoute('/users/')({
+  // tanstack §3.4 / core-rules §7.3: cross-route state (page, sort, filter) lives in the URL.
+  // SearchSchemaInput: every param is optional for <Link>, always present after validation.
+  validateSearch: (
+    search: Partial<UsersQuery> & SearchSchemaInput,
+  ): UsersQuery => UsersQuerySchema.parse(search),
+  search: { middlewares: [stripSearchParams<UsersQuery>(DEFAULT_USERS_QUERY)] },
+  head: () => ({ meta: [{ title: `Utenti — ${APP_NAME}` }] }),
+  component: UsersPage,
+})

package/templates/fe/base/src/stores/seam.test.ts

@@ -0,0 +1,21 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+/** State seam: only src/stores may import zustand/jotai; consumers go through `@/stores`. */
+const walk = (dir: string): string[] =>
+  readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name)
+    return statSync(path).isDirectory() ? walk(path) : [path]
+  })
+
+describe('state seam', () => {
+  it('no zustand/jotai import outside src/stores', () => {
+    const offenders = walk('src')
+      .filter(
+        (f) => /\.(ts|tsx)$/.test(f) && !f.startsWith(join('src', 'stores')),
+      )
+      .filter((f) => /from ['"](zustand|jotai)/.test(readFileSync(f, 'utf8')))
+    expect(offenders).toEqual([])
+  })
+})

package/templates/fe/base/src/test/api-mock.ts

@@ -0,0 +1,22 @@
+import { HttpResponse, type JsonBodyType, http } from 'msw'
+
+import { server } from './msw/server'
+
+/**
+ * Test seam over the HTTP mock: feature tests call these instead of touching MSW directly,
+ * so the `no-msw` variant can swap the implementation (axios adapter) without changing tests.
+ */
+export const apiMock = {
+  /** Next GET /api/users answers `status` with `body`. */
+  failOnce: (status: number, body: JsonBodyType) =>
+    server.use(
+      http.get('/api/users', () => HttpResponse.json(body, { status }), {
+        once: true,
+      }),
+    ),
+  /** Next GET /api/users answers 200 with `body`. */
+  respondOnce: (body: JsonBodyType) =>
+    server.use(
+      http.get('/api/users', () => HttpResponse.json(body), { once: true }),
+    ),
+}

package/templates/fe/base/src/test/fixtures/users.ts

@@ -0,0 +1,39 @@
+import type { User, UsersResponse } from '@/features/users/users.schema'
+
+const ROLES = ['admin', 'editor', 'viewer'] as const
+
+/** Deterministic fixture: 45 users → 3 pages of 20. Shared by unit tests (MSW) and e2e (page.route). */
+export const mockUsers: User[] = Array.from({ length: 45 }, (_, i) => ({
+  id: `u-${String(i + 1).padStart(3, '0')}`,
+  name: `User ${String(i + 1).padStart(3, '0')}`,
+  email: `user${i + 1}@example.test`,
+  role: ROLES[i % 3] ?? 'viewer',
+  createdAt: new Date(Date.UTC(2025, 0, 1 + i)).toISOString(),
+}))
+
+/** Mirrors the API's GET /api/users semantics (q, sort=-field, page, limit). */
+export const listUsers = (url: URL): UsersResponse => {
+  const page = Number(url.searchParams.get('page') ?? 1)
+  const limit = Number(url.searchParams.get('limit') ?? 20)
+  const q = (url.searchParams.get('q') ?? '').toLowerCase()
+  const sort = url.searchParams.get('sort') ?? 'name'
+  const desc = sort.startsWith('-')
+  const field = (desc ? sort.slice(1) : sort) as keyof User
+  const filtered = mockUsers
+    .filter(
+      (u) =>
+        !q ||
+        u.name.toLowerCase().includes(q) ||
+        u.email.toLowerCase().includes(q),
+    )
+    .sort(
+      (a, b) =>
+        String(a[field]).localeCompare(String(b[field])) * (desc ? -1 : 1),
+    )
+  return {
+    data: filtered.slice((page - 1) * limit, page * limit),
+    page,
+    limit,
+    total: filtered.length,
+  }
+}

package/templates/fe/base/src/test/msw/handlers.ts

@@ -0,0 +1,9 @@
+import { HttpResponse, http } from 'msw'
+
+import { listUsers } from '@/test/fixtures/users'
+
+export const handlers = [
+  http.get('/api/users', ({ request }) =>
+    HttpResponse.json(listUsers(new URL(request.url))),
+  ),
+]

package/templates/fe/base/src/test/msw/server.ts

@@ -0,0 +1,5 @@
+import { setupServer } from 'msw/node'
+
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)

package/templates/fe/base/src/test/render.tsx

@@ -0,0 +1,45 @@
+import type { ReactElement, ReactNode } from 'react'
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  RouterProvider,
+  createMemoryHistory,
+  createRouter,
+} from '@tanstack/react-router'
+
+import { render, renderHook } from '@testing-library/react'
+
+import { routeTree } from '@/routeTree.gen'
+import { StoreProvider } from '@/stores'
+
+/** Fresh QueryClient per test: no retries, no cache bleed. */
+export const createTestQueryClient = () =>
+  new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: 0 } } })
+
+/** Fresh state store + QueryClient per render. */
+export const createWrapper = (client = createTestQueryClient()) =>
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StoreProvider>
+        <QueryClientProvider client={client}>{children}</QueryClientProvider>
+      </StoreProvider>
+    )
+  }
+
+export const renderWithQuery = (ui: ReactElement) =>
+  render(ui, { wrapper: createWrapper() })
+
+export const renderHookWithQuery = <T,>(hook: () => T) =>
+  renderHook(hook, { wrapper: createWrapper() })
+
+/** Full app on an in-memory history: exercises routes, validateSearch and providers. */
+export const renderApp = (path: string) => {
+  const router = createRouter({
+    routeTree,
+    history: createMemoryHistory({ initialEntries: [path] }),
+  })
+  const utils = render(<RouterProvider router={router} />, {
+    wrapper: createWrapper(),
+  })
+  return { ...utils, router }
+}

package/templates/fe/base/src/test/setup.ts

@@ -0,0 +1,15 @@
+import '@testing-library/jest-dom/vitest'
+import { cleanup } from '@testing-library/react'
+import { afterAll, afterEach, beforeAll } from 'vitest'
+
+import { resetStores } from '@/stores'
+
+import { server } from './msw/server'
+
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
+afterEach(() => {
+  server.resetHandlers()
+  resetStores()
+  cleanup()
+})
+afterAll(() => server.close())

package/templates/fe/base/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "types": ["vite/client", "bun"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["src", "scripts", "e2e", "*.ts", "eslint.config.js"]
+}

package/templates/fe/base/vite.config.ts

@@ -0,0 +1,22 @@
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
+
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import path from 'node:path'
+import { defineConfig } from 'vite'
+
+// core-rules §9: port 3000 strict; mkcert/OIDC/MFE omitted (standalone template, see AGENTS.md).
+// tanstack-ecosystem §1.1: router plugin FIRST, autoCodeSplitting on.
+export default defineConfig({
+  plugins: [
+    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
+    react(),
+    tailwindcss(),
+  ],
+  resolve: { alias: { '@': path.resolve(import.meta.dirname, './src') } },
+  server: {
+    port: 3000,
+    strictPort: true,
+    proxy: { '/api': 'http://localhost:4000' },
+  },
+})