@happyvertical/smrt-template-sveltekit

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.5万

Minimal SvelteKit project template with s-m-r-t framework integration

原始使用文档
文档目录10 节
  1. 1. Install and run
  2. 2. Understand the generated files
  3. 3. Define the first object
  4. 4. Initialize or migrate the database
  5. 5. Understand tenant context
  6. 6. Understand users, profiles, memberships, roles, and perm…
  7. 7. Load data into a SvelteKit page
  8. 8. Use generated REST, MCP, WebMCP, and CLI interfaces
  9. 9. Add optional live browser data
  10. 10. Graduate to smrt-start

@happyvertical/smrt-template-sveltekit

The minimal “learn and build from the ground up” SvelteKit template for s-m-r-t. The package exports copyTemplate(), getTemplatePath(), and templateInfo and is the sveltekit template used by smrt gnode create.

1. Install and run

Scaffold through the public CLI:

node --input-type=module -e "import { copyTemplate } from './packages/template-sveltekit/index.js'; copyTemplate('./my-app', { name: 'my-app' })"
cd my-app
pnpm install
cp .env.example .env
pnpm app:install

Run the copy command from the monorepo root. smrt gnode create --template=sveltekit uses the same copyTemplate() export.

Generated projects require Node.js 26.0.0 or newer and pnpm 11.25.0. They pin all directly used @happyvertical/smrt-* packages to the current monorepo release, including opt-in MCP Apps dependencies (synced at publish by scripts/sync-template-versions.mjs; --check detects drift).

smrt gnode create <name> --mcp-apps supports installed, local, and Git subdirectory templates. Plugin names must satisfy the pinned Agent Plugins 1.0.0 schema before generation starts. smrt mcp-apps validate applies the official closed plugin/MCP schemas offline, then s-m-r-t endpoint and credential checks. Every existing scoped registry directive must be canonical; inline # and ; comments are supported. Hosted MCP caches its successfully created authenticator for the process, preserving JWKS keys across requests while principal resolution and task authorization still run for each request.

For programmatic scaffolding:

import { copyTemplate } from '@happyvertical/smrt-template-sveltekit';

copyTemplate('/absolute/path/to/my-app', {
  name: 'my-app',
  overwrite: false,
});

copyTemplate() turns an unscoped project name such as my-app into the runtime-safe package identity @smrt-app/my-app; explicitly scoped package names are preserved. It also excludes package-internal .svelte-kit and test fixtures.

2. Understand the generated files

The checked-in template contains authored objects, one server module (src/lib/server/smrt.ts, the runtime and its options), thin hooks and routes that mount package handlers, pages, and configuration. It ships no operator scripts. Vite generates .smrt/manifest.json, .smrt/smrt-knowledge.json, .smrt/register.js, src/lib/server/smrt-register.ts, src/lib/types/smrt-generated/, and src/routes/api/**/+server.ts. All are ignored and excluded from scaffold fixtures.

vite.config.ts is plugins: [sveltekit(), smrt()]: the @happyvertical/smrt-core/vite preset applies the decorator transform, scans the local object directory, generates local routes and types, and consumes the packages smrt.config.ts lists under consumer.packages (profiles, tenancy, users). @happyvertical/smrt-cli is a direct dev dependency because every lifecycle script is smrt app <operation>.

3. Define the first object

A new app ships with no object: src/lib/objects/index.ts is an empty barrel, the home page is an empty state, and nothing is registered or migrated.

The Note example is kept outside the template, in examples/notes/, as an src/-shaped tree you can copy into a generated app:

cp -r packages/template-sveltekit/examples/notes/src/. my-app/src/

It adds src/lib/objects/Note.ts (a required-tenant object with title and body fields, a small explicit NoteCollection that keeps generated CLI/MCP runtime commands constructible, and an @smrt() configuration that exposes CRUD to REST, MCP, WebMCP definitions, and CLI with an API writable allowlist) and a /notes page. Then:

  1. Export it in src/lib/objects/index.ts: export { Note, NoteCollection } from './Note.js';
  2. Link /notes from the nav array in src/routes/+layout.svelte.
  3. Run pnpm db:migrate.

Add your own objects the same way. vite.config.ts already scans src/lib/objects.

4. Initialize or migrate the database

Generated local projects use SQLite in the current user's operating-system application-data directory by default:

pnpm db:migrate

The script builds first to refresh manifests, registrations, types, and API routes, then runs smrt app migrate, which holds the operation lock and runs smrt db:migrate. The deprecated smrt db:setup command is not documented or shipped.

5. Understand tenant context

src/hooks.server.ts mounts createSmrtSvelteKitRuntime() from @happyvertical/smrt-app-runtime/sveltekit. It resolves a URL tenant candidate into separate selectedTenantId/selectedTenantSlug locals and does not establish query context from that selection. The session step runs afterward and only its membership-authorized tenant enters the s-m-r-t tenancy context.

Untrusted tenant headers are ignored. Applications may pass selectTenant for a path, signed-cookie, or trusted-gateway selector, but selection must remain separate from authorization and session switches must use switchSessionTenant().

6. Understand users, profiles, memberships, roles, and permissions

The generated project consumes the current profiles and users manifests and loads the signed session through the runtime, which enters tenant context only for a verified active membership. A User is the auth identity, Profile is person-facing metadata, Membership joins a User to a Tenant and Role, Role maps to Permission records, and Session publishes the resolved permission snapshot.

The example page's form action calls assertOperationPermission() with that exact snapshot. Provider-specific login and provisioning remain app-owned extension points.

7. Load data into a SvelteKit page

The example /notes page loads Note rows in +page.server.ts, returns plain serialized data, and declares depends('smrt:notes'). The Svelte 5 page reads hydrated $props() data and calls invalidate('smrt:notes') after a successful form mutation. It does not fetch initial data in onMount or $effect.

8. Use generated REST, MCP, WebMCP, and CLI interfaces

REST routes are generated under src/routes/api. MCP and WebMCP descriptors come from the same action metadata. CLI commands are available through the declared dev dependency:

pnpm smrt objects
pnpm smrt schema <YourObject>
pnpm smrt generate-mcp --no-config --no-readme

The root layout wires the generated webMcpToolDefinitions into the Provider, so each browser page exposes only read-effect generated model tools by default. Write and destructive effects require explicit page-owned opt-in, and all custom actions execute through their authenticated generated REST routes. For a smaller page-specific surface, pass a filtered definitions array or use the framework-agnostic registerWebMcpTools() API from @happyvertical/smrt-web. The CLI's manifest-only objects and schema commands work in this source-first template. Local-object CRUD execution through the generic CLI additionally requires a compiled JavaScript project entry point.

9. Add optional live browser data

@happyvertical/smrt-web is included on the synchronized release line because the root Provider loads the generated WebMCP definitions. No separate install is needed for WebMCP. Live browser collections remain opt-in per page; import the collection helpers only on pages that need interactive client data.

The generated-project README shows the current hydration pattern: createSmrtCollection(getCollectionDefinition('notes'), { initialData, basePath: '/api' }) followed by liveCollection(). The root layout's read-only WebMCP registration does not materialize live collections.

10. Graduate to smrt-start

Use this template for learning and focused, ground-up applications. Choose smrt-start, the canonical application template, when you want a production-shaped baseline. This package intentionally avoids becoming a second production starter.

The generated project has one canonical runtime.profile and deterministic app:* operations. Local state stays outside source. The production baseline uses adapter-node and includes a container plus separate task/schedule workers; Compose requires operator-supplied database secrets, and cloud examples describe provider composition without pretending to provision it. Install/start/stop/recover are local-profile commands; deployed web processes run the production Node build or container directly.

Every supported local web entry point (app:start or pnpm dev) shares one writer lease outside the source checkout. Direct production startup requires an explicit loopback HOST; prefer app:start. Filesystem backup and logical import fail closed while a writer is alive; logical export reads every model table from one transaction snapshot and reports that uploaded assets are excluded. The production image retains the generated manifest and operator CLI required by doctor/export/import.

版本与发布记录

@happyvertical/smrt-template-sveltekit 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-template-sveltekit 的常见问题

@happyvertical/smrt-template-sveltekit 是什么?

Minimal SvelteKit project template with s-m-r-t framework integration

如何安装 @happyvertical/smrt-template-sveltekit?

在项目目录运行 npm install @happyvertical/smrt-template-sveltekit,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:svelte(^5.57.1)、@sveltejs/kit(^2.70.3)、@happyvertical/sql(>=0.89.12)、@happyvertical/smrt-ui(0.62.1)、@happyvertical/smrt-chat(0.62.1)、@happyvertical/smrt-core(0.62.1)、@happyvertical/smrt-jobs(0.62.1)、@happyvertical/smrt-types(0.62.1)、@happyvertical/smrt-users(0.62.1)、@happyvertical/smrt-agents(0.62.1)、@happyvertical/smrt-svelte(0.62.1)、@happyvertical/smrt-app-mcp(0.62.1)、@happyvertical/smrt-prompts(0.62.1)、@happyvertical/smrt-tenancy(0.62.1)、@happyvertical/smrt-inference(0.62.1)、@happyvertical/smrt-workflows(0.62.1)、@happyvertical/smrt-app-runtime(0.62.1)、@happyvertical/smrt-preferences(0.62.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@happyvertical/smrt-template-sveltekit 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-template-sveltekit 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-template-sveltekit 可以商用吗?

@happyvertical/smrt-template-sveltekit 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-template-sveltekit 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-template-sveltekit 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,644 次,日均约 488 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-template-sveltekit 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 365 个版本,其中过去 12 个月发布了 365 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。