跳到主要内容

快速开始

快速入门

五分钟内你将拥有一个微小但完整的工作区：一个集合、一个应用，以及一个构建好的产物。同一份源码可以本地构建，也可以在你托管到 Colony 时通过 工作区工作室构建。

src/
├── collections/
│   ├── +relationship.ts        # relationship registry (required)
│   └── tasks/
│       └── +model.ts           # the collection
└── apps/
    └── +tasks.svelte           # the app

1. 配置 Vite 与 TypeScript

从一个普通的 Vite 项目开始，然后添加 Bolt 插件。该插件负责整个构建。

// vite.config.ts
import { bolt } from '@norbital-ai/bolt/vite';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [bolt()] });
// tsconfig.json
{ "extends": "./.norbital/tsconfig.json" }

2. 定义一个集合

创建 src/collections/tasks/+model.ts 。目录名 tasks 就是集合 ID；模型只声明字段与选项，不声明其他任何内容。

// src/collections/tasks/+model.ts
import { defineModel, enums, text } from '@norbital-ai/bolt/authoring';

export default defineModel(
  {
    title: text().notNull(),
    status: enums(['open', 'done']).notNull().default('open')
  },
  { description: 'Task', recordLabel: 'title' }
);

3. 添加关联注册表

创建 src/collections/+relationship.ts 。每个工作区恰好需要一份这样的文件；所有集合关联都在这里声明。

// src/collections/+relationship.ts
import type { Relationships } from './$types.js';

export default ((r) => ({
  tasks: {}
})) satisfies Relationships;

4. 添加一个应用

创建 src/apps/+tasks.svelte 。应用就是普通的 Svelte 组件；文件名即应用 ID。 CollectionTable 使用由模式派生的表单渲染你的集合，并内置创建/编辑功能——它通过 实时查询 读取数据，因此表格会随数据变化保持实时。

<!-- src/apps/+tasks.svelte -->
<script lang="ts">
  import { CollectionTable } from '@norbital-ai/ui/collection-table';
  import { Stack } from '@norbital-ai/ui/layout';
  import { PageHeader } from '@norbital-ai/ui/page-header';
</script>

<svelte:head>
  <title>Tasks</title>
  <meta name="bolt:icon" content="lucide:list-todo" />
</svelte:head>

<Stack gap="lg">
  <PageHeader title="Tasks" description="Everything the team is working on." />
  <CollectionTable collection="tasks">
    {#snippet columns({ Column })}
      <Column name="title" />
      <Column name="status" />
    {/snippet}
  </CollectionTable>
</Stack>

5. 同步

bolt sync
  • bolt sync 运行 文件系统编译器 ：它校验角色文件（带 `+` 前缀但没有角色的文件是错误），生成 .norbital/tsconfig.json 、注册表模块和本地的 $types .
  • bolt sync 还会把客户端构建到 .norbital/dist/ ，并把可移植的服务器产物输出到 .norbital/artifact/ .
两种不同的 “sync”
bolt sync 是 文件系统编译器 ，每次保存时校验并重新生成类型。 数据同步引擎 则是保持运行中的应用内实时查询更新的运行时层。同一个词，不同的工作。

下一步

你现在拥有了一个可构建的工作区。从这里开始：