@pauldvlp/vp-react-ts-nestjs 0.1.0

package/template/apps/api/src/health/health.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common'
+
+import { HealthController } from './health.controller'
+
+@Module({
+  controllers: [HealthController]
+})
+export class HealthModule {}

package/template/apps/api/src/items/items.controller.ts

@@ -0,0 +1,25 @@
+import { Body, Controller, Get, Param, Post } from '@nestjs/common'
+import { createItemSchema, type CreateItem, type Item } from '@app/contracts'
+
+import { ZodValidationPipe } from '../common/zod-validation.pipe'
+import { ItemsService } from './items.service'
+
+@Controller('items')
+export class ItemsController {
+  constructor(private readonly items: ItemsService) {}
+
+  @Get()
+  findAll(): Item[] {
+    return this.items.findAll()
+  }
+
+  @Get(':id')
+  findOne(@Param('id') id: string): Item {
+    return this.items.findOne(id)
+  }
+
+  @Post()
+  create(@Body(new ZodValidationPipe(createItemSchema)) body: CreateItem): Item {
+    return this.items.create(body)
+  }
+}

package/template/apps/api/src/items/items.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common'
+
+import { ItemsController } from './items.controller'
+import { ItemsService } from './items.service'
+
+@Module({
+  controllers: [ItemsController],
+  providers: [ItemsService]
+})
+export class ItemsModule {}

package/template/apps/api/src/items/items.service.spec.ts

@@ -0,0 +1,26 @@
+import { Test } from '@nestjs/testing'
+import { beforeEach, describe, expect, it } from 'vite-plus/test'
+
+import { ItemsService } from './items.service'
+
+// Building the module through Nest's DI container is the real proof that decorator metadata is being
+// emitted by vite-plus's Oxc transform — without it, `Test.createTestingModule(...).compile()` would throw.
+describe('ItemsService', () => {
+  let service: ItemsService
+
+  beforeEach(async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [ItemsService] }).compile()
+    service = moduleRef.get(ItemsService)
+  })
+
+  it('creates and lists items', () => {
+    const created = service.create({ name: 'first' })
+    expect(created.id).toBeTruthy()
+    expect(service.findAll()).toHaveLength(1)
+    expect(service.findOne(created.id)).toEqual(created)
+  })
+
+  it('throws for an unknown id', () => {
+    expect(() => service.findOne('nope')).toThrow()
+  })
+})

package/template/apps/api/src/items/items.service.ts

@@ -0,0 +1,24 @@
+import { Injectable, NotFoundException } from '@nestjs/common'
+import type { CreateItem, Item } from '@app/contracts'
+
+/** A throwaway in-memory store so the template runs with zero infra. Swap for a real repository. */
+@Injectable()
+export class ItemsService {
+  private readonly items: Item[] = []
+
+  findAll(): Item[] {
+    return this.items
+  }
+
+  findOne(id: string): Item {
+    const item = this.items.find((i) => i.id === id)
+    if (!item) throw new NotFoundException(`Item ${id} not found`)
+    return item
+  }
+
+  create(input: CreateItem): Item {
+    const item: Item = { id: crypto.randomUUID(), name: input.name, createdAt: new Date().toISOString() }
+    this.items.push(item)
+    return item
+  }
+}

package/template/apps/api/src/main.ts

@@ -0,0 +1,30 @@
+import 'reflect-metadata'
+
+import { NestFactory } from '@nestjs/core'
+import { Logger } from 'nestjs-pino'
+// __SWAGGER_IMPORT__
+import { AppModule } from './app.module'
+import { ENV, type Env } from './config/env'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { bufferLogs: true })
+  app.useLogger(app.get(Logger))
+  app.setGlobalPrefix('api')
+  // __SWAGGER_SETUP__
+  const env = app.get<Env>(ENV)
+  await app.listen(env.PORT)
+  return app
+}
+
+const app = bootstrap()
+
+// Clean restart under `vite-node --watch`: `accept()` makes vite-node re-execute this module in place
+// (a plain change would full-reload without disposing), and `dispose` closes the running server first
+// so the next bootstrap() doesn't hit EADDRINUSE on the same port. `import.meta.hot` is undefined in
+// the production SSR build, so this whole block is tree-shaken away there.
+if (import.meta.hot) {
+  import.meta.hot.accept()
+  import.meta.hot.dispose(async () => {
+    await (await app).close()
+  })
+}

package/template/apps/api/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["ES2023"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": ["node", "vite/client"],
+
+    /* NestJS needs decorators + metadata; param properties and decorators are emitted by vite-plus's
+       Oxc transform, so `erasableSyntaxOnly` / `verbatimModuleSyntax` are intentionally left off here. */
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+
+    "strict": true,
+    "strictPropertyInitialization": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/template/apps/api/vite.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig } from 'vite-plus'
+
+// NestJS relies on `emitDecoratorMetadata` for its dependency injection. vite-plus's built-in Oxc
+// transform emits it natively (driven by `experimentalDecorators` + `emitDecoratorMetadata` in
+// tsconfig.json), so no extra transform plugin is needed — the api is a plain vite-plus package and
+// `vp check` / `vp test` pick it up with zero wiring.
+export default defineConfig({
+  build: {
+    // SSR build: bundle the entry to dist/main.js and externalize node_modules (so Nest's optional
+    // dynamic requires aren't dragged into the bundle). The workspace contracts package is source
+    // TypeScript, so it must be inlined rather than externalized — see `ssr.noExternal` below.
+    ssr: 'src/main.ts',
+    outDir: 'dist',
+    target: 'node22'
+  },
+  ssr: {
+    noExternal: ['@app/contracts']
+  },
+  lint: {
+    plugins: ['typescript', 'oxc'],
+    rules: {
+      'vite-plus/prefer-vite-plus-imports': 'error'
+    },
+    options: {
+      typeAware: true,
+      typeCheck: true
+    },
+    jsPlugins: [
+      {
+        name: 'vite-plus',
+        specifier: 'vite-plus/oxlint-plugin'
+      }
+    ]
+  }
+})

package/template/apps/web/_gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/template/apps/web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>web</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/apps/web/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@app/web",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vp dev",
+    "build": "tsc -b && vp build",
+    "lint": "vp lint",
+    "preview": "vp preview"
+  },
+  "dependencies": {
+    "@app/contracts": "workspace:*",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@rolldown/plugin-babel": "catalog:",
+    "@types/node": "^24.13.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.2",
+    "typescript": "~6.0.2",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}

package/template/apps/web/public/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32">
+  <rect width="32" height="32" rx="7" fill="#0b0b0b" />
+  <path d="M9 10l4.5 12h2L20 10h-2.6l-2.9 8.3L11.6 10z" fill="#e3d000" />
+</svg>

package/template/apps/web/src/App.tsx

@@ -0,0 +1,48 @@
+import type { Item } from '@app/contracts'
+import { useEffect, useState, type FormEvent } from 'react'
+
+// `/api/*` is proxied to the NestJS server in dev (see vite.config.ts), so these are same-origin calls.
+const fetchItems = (): Promise<Item[]> => fetch('/api/items').then((res) => res.json())
+
+const createItem = (name: string): Promise<Item> =>
+  fetch('/api/items', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name })
+  }).then((res) => res.json())
+
+export const App = () => {
+  const [items, setItems] = useState<Item[]>([])
+  const [name, setName] = useState('')
+
+  useEffect(() => {
+    void fetchItems().then(setItems)
+  }, [])
+
+  const add = async (event: FormEvent) => {
+    event.preventDefault()
+    if (!name.trim()) return
+    const created = await createItem(name.trim())
+    setItems((prev) => [...prev, created])
+    setName('')
+  }
+
+  return (
+    <main style={{ fontFamily: 'system-ui, sans-serif', maxWidth: 480, margin: '4rem auto', padding: '0 1rem' }}>
+      <h1>Vite+ · React + NestJS</h1>
+      <p>A minimal full-stack starter. The list below is served by the NestJS api.</p>
+
+      <form onSubmit={add} style={{ display: 'flex', gap: 8, margin: '1.5rem 0' }}>
+        <input value={name} onChange={(event) => setName(event.target.value)} placeholder='New item name' style={{ flex: 1, padding: 8 }} />
+        <button type='submit'>Add</button>
+      </form>
+
+      <ul>
+        {items.map((item) => (
+          <li key={item.id}>{item.name}</li>
+        ))}
+      </ul>
+      {items.length === 0 && <p style={{ opacity: 0.6 }}>No items yet — add one above.</p>}
+    </main>
+  )
+}

package/template/apps/web/src/main.tsx

@@ -0,0 +1,9 @@
+import { App } from '@app/web/App'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+)

package/template/apps/web/tsconfig.app.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite-plus/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+
+    /* Aliases */
+    "paths": {
+      "@app/web/*": ["./src/*"],
+      "@app/contracts": ["../../packages/contracts/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/template/apps/web/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "files": [],
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}

package/template/apps/web/tsconfig.node.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

package/template/apps/web/vite.config.ts

@@ -0,0 +1,45 @@
+import babel from '@rolldown/plugin-babel'
+import react, { reactCompilerPreset } from '@vitejs/plugin-react'
+import { fileURLToPath, URL } from 'url'
+import { defineConfig, lazyPlugins } from 'vite-plus'
+
+// https://vite.dev/config/
+export default defineConfig({
+  server: {
+    port: __WEB_PORT__,
+    // Same-origin in dev: requests to `/api/*` are forwarded to the NestJS server, so no CORS and no
+    // absolute API URLs in the client code.
+    proxy: {
+      '/api': 'http://localhost:__API_PORT__'
+    }
+  },
+  lint: {
+    plugins: ['react', 'typescript', 'oxc'],
+    rules: {
+      'react/rules-of-hooks': 'error',
+      'react/only-export-components': [
+        'warn',
+        {
+          allowConstantExport: true
+        }
+      ],
+      'vite-plus/prefer-vite-plus-imports': 'error'
+    },
+    options: {
+      typeAware: true,
+      typeCheck: true
+    },
+    jsPlugins: [
+      {
+        name: 'vite-plus',
+        specifier: 'vite-plus/oxlint-plugin'
+      }
+    ]
+  },
+  plugins: lazyPlugins(() => [react(), babel({ presets: [reactCompilerPreset()] })]),
+  resolve: {
+    alias: {
+      '@app/web': fileURLToPath(new URL('./src', import.meta.url))
+    }
+  }
+})

package/template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vp run -r dev",
+    "build": "vp run -r build",
+    "check": "vp check",
+    "ready": "vp check && vp run -r build"
+  },
+  "devDependencies": {
+    "babel-plugin-react-compiler": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.9.0",
+      "onFail": "download"
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

package/template/packages/contracts/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@app/contracts",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "lint": "vp lint",
+    "check": "vp check"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}

package/template/packages/contracts/src/index.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod'
+
+/**
+ * Shared API contracts. Both ends import from here so there is a single source of truth:
+ * the api validates request bodies against these schemas (via the ZodValidationPipe) and the
+ * web app uses the inferred types to type its `fetch` responses.
+ */
+
+export const itemSchema = z.object({
+  id: z.string(),
+  name: z.string().min(1),
+  createdAt: z.string()
+})
+
+export const createItemSchema = itemSchema.pick({ name: true })
+
+export type Item = z.infer<typeof itemSchema>
+export type CreateItem = z.infer<typeof createItemSchema>

package/template/packages/contracts/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": ["vite-plus/client"],
+    "skipLibCheck": true,
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["src", "vite.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/packages/contracts/vite.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vite-plus'
+
+export default defineConfig({
+  lint: {
+    plugins: ['typescript', 'oxc'],
+    rules: {
+      'vite-plus/prefer-vite-plus-imports': 'error'
+    },
+    options: {
+      typeAware: true,
+      typeCheck: true
+    },
+    jsPlugins: [
+      {
+        name: 'vite-plus',
+        specifier: 'vite-plus/oxlint-plugin'
+      }
+    ]
+  }
+})

package/template/pnpm-workspace.yaml

@@ -0,0 +1,29 @@
+packages:
+  - apps/*
+  - packages/*
+
+catalogMode: prefer
+
+catalog:
+  '@types/node': ^24
+  typescript: ^5
+  vite: npm:@voidzero-dev/vite-plus-core@latest
+  vitest: 4.1.9
+  vite-plus: ^0.2.1
+  babel-plugin-react-compiler: ^1.0.0
+  '@rolldown/plugin-babel': ^0.2.3
+overrides:
+  vite: 'catalog:'
+  vitest: 'catalog:'
+peerDependencyRules:
+  allowAny:
+    - vite
+    - vitest
+  allowedVersions:
+    vite: '*'
+    vitest: '*'
+allowBuilds:
+  esbuild: true
+  # Telemetry-only postinstall pulled transitively via @nestjs/swagger -> swagger-ui-dist. Declared
+  # explicitly (false = do not run) so pnpm doesn't fail with ERR_PNPM_IGNORED_BUILDS.
+  '@scarf/scarf': false

package/template/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "allowImportingTsExtensions": true,
+    "esModuleInterop": true
+  }
+}

package/template/vite.config.ts

@@ -0,0 +1,24 @@
+import { defaultExclude, defineConfig } from 'vite-plus'
+
+export default defineConfig({
+  test: {
+    // vite-plus's defaultExclude is only node_modules + .git (no dist), so a root-level
+    // `vp test` would otherwise scan compiled build output. Keep build outputs out of the scan.
+    exclude: [...defaultExclude, '**/dist/**', '**/build/**']
+  },
+  fmt: {
+    jsxSingleQuote: true,
+    printWidth: 160,
+    semi: false,
+    singleQuote: true,
+    trailingComma: 'none'
+  },
+  lint: {
+    jsPlugins: [{ name: 'vite-plus', specifier: 'vite-plus/oxlint-plugin' }],
+    rules: { 'vite-plus/prefer-vite-plus-imports': 'error' },
+    options: { typeAware: true, typeCheck: true }
+  },
+  run: {
+    cache: true
+  }
+})