Skip to content

Commit 35838fb

Browse files
hotlonghotlong
committed
Add Getting Started and Installation guides; update documentation structure
1 parent df1c0c1 commit 35838fb

7 files changed

Lines changed: 193 additions & 9 deletions

File tree

‎apps/docs/app/page.tsx‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,19 +27,17 @@ export default function HomePage() {
2727

2828
<div className="flex flex-col sm:flex-row items-center justify-center gap-4 pt-4">
2929
<Link
30-
href="/docs"
30+
href="/docs/guides/getting-started"
3131
className="inline-flex h-12 items-center justify-center rounded-lg bg-fd-primary px-8 text-sm font-medium text-fd-primary-foreground shadow-lg shadow-fd-primary/20 transition-all hover:bg-fd-primary/90 hover:scale-105 hover:shadow-fd-primary/30 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring disabled:pointer-events-none disabled:opacity-50"
3232
>
33-
Read the Specification
33+
Start Building
3434
</Link>
35-
<a
36-
href="https://github.com/objectstack-ai/spec"
37-
target="_blank"
38-
rel="noreferrer"
35+
<Link
36+
href="/docs"
3937
className="inline-flex h-12 items-center justify-center rounded-lg border border-fd-border bg-fd-card/50 px-8 text-sm font-medium shadow-sm transition-all hover:bg-fd-accent hover:text-fd-accent-foreground backdrop-blur-sm hover:scale-105 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring disabled:pointer-events-none disabled:opacity-50"
4038
>
41-
View on GitHub
42-
</a>
39+
Read Specification
40+
</Link>
4341
</div>
4442

4543
{/* Code Preview Decorator */}

‎content/docs/guides/getting-started.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: Getting Started
3+
description: Build your first ObjectStack application in 5 minutes.
4+
---
5+
6+
import { Step, Steps } from 'fumadocs-ui/components/steps';
7+
8+
ObjectStack is a protocol, but `@objectstack/spec` is the reference implementation library that provides the Zod schemas and strict types to build valid metadata.
9+
10+
<Steps>
11+
12+
<Step>
13+
## Initialize your project
14+
15+
You can start from scratch or add ObjectStack to an existing TypeScript project.
16+
17+
```bash
18+
mkdir my-app
19+
cd my-app
20+
npm init -y
21+
npm install typescript zod @objectstack/spec
22+
npx tsc --init
23+
```
24+
</Step>
25+
26+
<Step>
27+
## Define your first Object
28+
29+
Create a file named `src/objects/contact.schema.ts`.
30+
This is where the power of **Zod-First Definition** comes in. You get autocomplete and validation out of the box.
31+
32+
```typescript
33+
import { ObjectSchema, Field } from '@objectstack/spec';
34+
35+
export const Contact = ObjectSchema.create({
36+
name: 'contact',
37+
label: 'Contact',
38+
fields: {
39+
first_name: Field.text({ label: 'First Name', required: true }),
40+
last_name: Field.text({ label: 'Last Name', required: true }),
41+
email: Field.text({ format: 'email' }),
42+
type: Field.select(['Customer', 'Partner', 'Vendor']),
43+
},
44+
enable: {
45+
api: true,
46+
audit: true
47+
}
48+
});
49+
```
50+
</Step>
51+
52+
<Step>
53+
## Validate the Protocol
54+
55+
Create a build script `src/build.ts` to verify your definitions comply with the ObjectStack Protocol.
56+
57+
```typescript
58+
import { Contact } from './objects/contact.schema';
59+
60+
// This will throw a ZodError if your schema is invalid
61+
const protocol = Contact.parse(Contact);
62+
63+
console.log(`✅ Object '${protocol.name}' is valid ObjectStack Metadata!`);
64+
console.log(JSON.stringify(protocol, null, 2));
65+
```
66+
</Step>
67+
68+
<Step>
69+
## Next Steps
70+
71+
Now that you have valid metadata, you can:
72+
73+
1. **Generate SQL**: Use the Protocol Compiler (Coming Soon) to generate `CREATE TABLE` statements.
74+
2. **Generate UI**: Feed the JSON into the `<ObjectForm />` React component.
75+
3. **Deploy**: Push the JSON to an ObjectOS Kernel.
76+
77+
</Step>
78+
79+
</Steps>

‎content/docs/guides/installation.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Installation
3+
description: Installing the ObjectStack SDK and CLI.
4+
---
5+
6+
## Requirements
7+
8+
* Node.js 18+
9+
* TypeScript 5+
10+
11+
## Package Installation
12+
13+
The `@objectstack/spec` package contains the core Zod Definitions and Type Interfaces.
14+
15+
### npm
16+
17+
```bash
18+
npm install @objectstack/spec
19+
```
20+
21+
### pnpm
22+
23+
```bash
24+
pnpm add @objectstack/spec
25+
```
26+
27+
### yarn
28+
29+
```bash
30+
yarn add @objectstack/spec
31+
```
32+
33+
## CLI Installation (Optional)
34+
35+
The CLI tool helps scaffold new objects and validate existing metadata.
36+
37+
```bash
38+
npm install -g @objectstack/cli
39+
```
40+
41+
## Versioning
42+
43+
The Protocol follows Semantic Versioning.
44+
* **Major (1.x)**: Breaking changes to the Protocol (JSON Structure).
45+
* **Minor (1.1.x)**: New Field Types or Configuration Options.
46+
* **Patch (1.1.1)**: Bug fixes in Zod validation or Type inference.

‎content/docs/guides/meta.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"title": "Developer Guides",
3+
"pages": [
4+
"getting-started",
5+
"installation",
6+
"project-structure"
7+
]
8+
}

‎content/docs/guides/project-structure.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Project Structure
3+
description: Recommended directory layout for ObjectStack projects.
4+
---
5+
6+
import { File, Folder } from 'lucide-react';
7+
8+
To keep your metadata organized, we recommend the following folder structure ("The Domain Pattern").
9+
10+
<Files>
11+
<Folder name="src" defaultOpen>
12+
<Folder name="domains" defaultOpen>
13+
<Folder name="crm" defaultOpen>
14+
<File name="contact.object.ts" />
15+
<File name="account.object.ts" />
16+
<File name="lead.object.ts" />
17+
</Folder>
18+
<Folder name="finance" defaultOpen>
19+
<File name="invoice.object.ts" />
20+
<File name="payment.object.ts" />
21+
</Folder>
22+
</Folder>
23+
<Folder name="apps">
24+
<File name="backoffice.app.ts" />
25+
<File name="portal.app.ts" />
26+
</Folder>
27+
<Folder name="config">
28+
<File name="datasources.ts" />
29+
<File name="acl.ts" />
30+
</Folder>
31+
</Folder>
32+
<File name="package.json" />
33+
<File name="tsconfig.json" />
34+
<File name="objectstack.config.ts" />
35+
</Files>
36+
37+
## Key Concepts
38+
39+
### Domains
40+
Organize your Objects by Business Domain (CRM, Finance, HR) rather than by technical type. This aligns with **Domain-Driven Design (DDD)** principles.
41+
42+
### Naming Conventions
43+
44+
* **Files**: `kebab-case.suffix.ts` (e.g., `project-task.object.ts`, `main-dashboard.view.ts`)
45+
* **Variables**: `PascalCase` (e.g., `ProjectTask`, `MainDashboard`)
46+
* **Machine Names**: `snake_case` inside the definition (e.g., `name: 'project_task'`)

‎content/docs/index.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,17 @@ This documentation is the authoritative reference for the ObjectStack Protocol.
1313
## How to navigate
1414

1515
<Cards>
16+
<Card
17+
icon={<FileText />}
18+
title="Getting Started"
19+
href="/docs/guides/getting-started"
20+
description="Build your first Object in 5 minutes. Learn the basics of the SDK."
21+
/>
1622
<Card
1723
icon={<Compass />}
1824
title="Concepts"
1925
href="/docs/concepts/manifesto"
20-
description="Start here. Understand the philosophy of 'Intent over Implementation' and the 'Local-First' architecture."
26+
description="Understand the philosophy of 'Intent over Implementation' and the 'Local-First' architecture."
2127
/>
2228
<Card
2329
icon={<Layers />}

‎content/docs/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
"title": "Documentation",
33
"pages": [
44
"index",
5+
"guides",
56
"concepts",
67
"specifications",
78
"references"

0 commit comments

Comments
 (0)