Skip to content

Commit b2e1047

Browse files
hotlonghotlong
authored
Merge pull request #641 from objectstack-ai/copilot/improve-developer-experience
2 parents e6dcffa + 0d583bc commit b2e1047

1 file changed

Lines changed: 365 additions & 0 deletions

File tree

‎DX_ROADMAP.md‎

Lines changed: 365 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,365 @@
1+
# ObjectStack — Developer Experience (DX) Roadmap
2+
3+
> **Date:** 2026-02-12
4+
> **Scope:** Post v3.0 — Focused entirely on Developer Experience
5+
> **Based On:** Full codebase scan + documentation audit (171 schemas, 191 test files, 40+ doc pages, 4 examples, 19 packages)
6+
> **Previous:** `ROADMAP.md` (v3.0 Phases 5–11 ✅ Complete)
7+
8+
---
9+
10+
## Executive Summary
11+
12+
ObjectStack v3.0 delivered a production-grade protocol spec with comprehensive type safety, test coverage, security hardening, and build tooling. The **next frontier is developer adoption** — making it effortless for developers to discover, learn, and build with the platform.
13+
14+
This roadmap prioritizes improvements based on the **"Time to First Wow"** metric: how quickly a new developer goes from `npm init` to a running application with data, UI, and API.
15+
16+
### Current DX Assessment
17+
18+
| Area | Score | Notes |
19+
|------|-------|-------|
20+
| **Type Safety** | ⭐⭐⭐⭐⭐ | Zod-first, 7,095+ `.describe()`, full inference |
21+
| **Schema Completeness** | ⭐⭐⭐⭐⭐ | 171 schemas, 1,470 JSON Schemas, OpenAPI 3.1 |
22+
| **Test Coverage** | ⭐⭐⭐⭐⭐ | 191 test files, 5,157+ tests |
23+
| **IDE Autocomplete** | ⭐⭐⭐⭐ | Bundled `objectstack.json`, `.describe()` tooltips |
24+
| **Getting Started** | ⭐⭐⭐ | Docs exist but no interactive playground |
25+
| **Error Messages** | ⭐⭐⭐ | Zod defaults + some custom refinements |
26+
| **Helper Functions** | ⭐⭐⭐ | `Field.*` excellent; `ObjectSchema.create()`, `defineStack()` minimal |
27+
| **Reference Docs** | ⭐⭐⭐ | API docs generated but no field type gallery or error code reference |
28+
| **Examples** | ⭐⭐⭐ | 4 examples but missing "How to Run" instructions |
29+
| **Migration Story** | ⭐⭐ | V3 guide exists but no automated `codemod` tooling |
30+
31+
---
32+
33+
## Phase 1: First Five Minutes (Onboarding) — 2 weeks
34+
35+
> **Goal:** A new developer runs `npx create-objectstack` and has a working app in under 5 minutes.
36+
> **Metric:** Time from `npm init` → running app with CRUD UI < 5 min.
37+
38+
### 1.1 Interactive Playground
39+
40+
| Task | Details | Priority |
41+
|------|---------|----------|
42+
| StackBlitz starter template | Pre-configured `app-todo` example on StackBlitz with "Open in Editor" button | 🔴 High |
43+
| "Try Online" button in README | One-click link in `packages/spec/README.md` and docs site | 🔴 High |
44+
| CodeSandbox template | Alternative playground for CodeSandbox users | 🟡 Medium |
45+
46+
### 1.2 Quick-Start Improvements
47+
48+
| Task | Details | Priority |
49+
|------|---------|----------|
50+
| Prerequisites check page | Add Node 18+, pnpm requirement callouts to getting-started/index.mdx | 🔴 High |
51+
| "How to Run" in every example | Add copy-paste commands + expected output to each example README | 🔴 High |
52+
| First-run troubleshooting guide | Common issues: pnpm install fails, port conflicts, TypeScript version | 🟡 Medium |
53+
| 5-minute video walkthrough | Screen recording of `create-objectstack` → running app | 🟡 Medium |
54+
55+
### 1.3 `create-objectstack` Scaffolding
56+
57+
| Task | Details | Priority |
58+
|------|---------|----------|
59+
| Interactive project wizard | `npx create-objectstack` with prompts: name, template, driver, framework | 🔴 High |
60+
| Template: Minimal API | Server + memory driver + 1 object + REST API | 🔴 High |
61+
| Template: Full-Stack | Server + UI + auth + 3 objects (CRM-lite) | 🟡 Medium |
62+
| Template: Plugin | Bare plugin skeleton with test setup | 🟡 Medium |
63+
64+
### Phase 1 Checklist
65+
66+
- [ ] Create StackBlitz starter template from `app-todo`
67+
- [ ] Add "Try Online" button to spec README.md and docs site hero
68+
- [ ] Add "How to Run" section to each example README (app-todo, app-crm, app-host)
69+
- [ ] Add prerequisites section to getting-started docs
70+
- [ ] Create first-run troubleshooting page
71+
- [ ] Implement `create-objectstack` CLI wizard with 3 templates
72+
- [ ] Record 5-minute getting-started video
73+
74+
---
75+
76+
## Phase 2: Schema DX Helpers — 2 weeks
77+
78+
> **Goal:** Make defining objects, views, and flows feel as natural as writing a React component.
79+
> **Metric:** Lines of code to define a complete CRUD object < 20 LOC.
80+
81+
### 2.1 Enhanced Factory Functions
82+
83+
| Task | Details | Priority |
84+
|------|---------|----------|
85+
| `ObjectSchema.create()` with defaults | Auto-generate `label` from `name`, merge common fields (id, created_at, updated_at), validate fields | 🔴 High |
86+
| `defineView()` helper | Type-safe view builder: `defineView({ object: 'task', type: 'grid', columns: [...] })` | 🔴 High |
87+
| `defineApp()` helper | Type-safe app builder: `defineApp({ name: 'crm', navigation: [...] })` | 🟡 Medium |
88+
| `defineFlow()` helper | Type-safe flow builder: `defineFlow({ trigger: 'record_create', steps: [...] })` | 🟡 Medium |
89+
| `defineAgent()` helper | Type-safe agent builder: `defineAgent({ role: 'support', tools: [...] })` | 🟡 Medium |
90+
91+
### 2.2 Improved Validation Error Messages
92+
93+
| Task | Details | Priority |
94+
|------|---------|----------|
95+
| Custom Zod error map for ObjectStack | Contextual errors: "Field 'status' has type 'select' but is missing required 'options' property" | 🔴 High |
96+
| Actionable error suggestions | Include "Did you mean?" suggestions for common typos (e.g., `text_area` → `textarea`) | 🟡 Medium |
97+
| Validation error formatter | Pretty-print validation errors with path highlighting for CLI output | 🟡 Medium |
98+
| Schema-aware diagnostics | Custom refinements that check cross-field consistency (e.g., lookup requires `reference`) | 🟡 Medium |
99+
100+
### 2.3 Type-Safe Patterns
101+
102+
| Task | Details | Priority |
103+
|------|---------|----------|
104+
| Branded types for identifiers | `ObjectName`, `FieldName`, `ViewName` branded types for compile-time safety | 🟡 Medium |
105+
| Strict mode for `defineStack()` | Optional strict mode that validates all cross-references (e.g., view references valid object) | 🟡 Medium |
106+
| Generic type parameters | `defineStack<Objects>()` that infers object names for type-safe view.object references | 🟢 Low |
107+
108+
### Phase 2 Checklist
109+
110+
- [ ] Enhance `ObjectSchema.create()` with auto-label, common fields, and validation
111+
- [ ] Implement `defineView()` with column type inference
112+
- [ ] Implement `defineApp()` with navigation builder
113+
- [ ] Implement `defineFlow()` with step type inference
114+
- [ ] Create custom Zod error map with contextual messages
115+
- [ ] Add "Did you mean?" suggestions for FieldType typos
116+
- [ ] Create pretty-print validation error formatter for CLI
117+
- [ ] Add branded types for ObjectName, FieldName, ViewName
118+
- [ ] Add strict cross-reference validation mode to `defineStack()`
119+
120+
---
121+
122+
## Phase 3: Documentation & Reference — 3 weeks
123+
124+
> **Goal:** Every schema has a visual reference page; every error has a documented solution.
125+
> **Metric:** 100% of user-facing schemas have a dedicated reference page with examples.
126+
127+
### 3.1 Field Type Gallery
128+
129+
| Task | Details | Priority |
130+
|------|---------|----------|
131+
| Visual field type reference | Interactive page showing all 46+ field types with live previews | 🔴 High |
132+
| Field configuration reference | Per-type property tables (text: maxLength, pattern; number: min, max, precision) | 🔴 High |
133+
| Field type decision tree | "Which field type should I use?" interactive guide | 🟡 Medium |
134+
| Field validation rules per type | Default validation behavior for each field type | 🟡 Medium |
135+
136+
### 3.2 Error & Status Code Reference
137+
138+
| Task | Details | Priority |
139+
|------|---------|----------|
140+
| Error code catalog | All 46 error codes with descriptions, causes, and fixes | 🔴 High |
141+
| HTTP status mapping table | Error category → HTTP status → retry strategy | 🟡 Medium |
142+
| Client-side error handling guide | Patterns for handling errors in React/Vue/vanilla JS | 🟡 Medium |
143+
| Server-side error handling guide | How to throw and format errors from plugins | 🟡 Medium |
144+
145+
### 3.3 Protocol Documentation
146+
147+
| Task | Details | Priority |
148+
|------|---------|----------|
149+
| Protocol relationship diagram | Visual diagram showing how Data → API → UI layers connect | 🔴 High |
150+
| Query syntax cheat sheet | One-page reference for QuerySchema filters, sorts, pagination | 🔴 High |
151+
| Wire format examples | JSON request/response examples for every API endpoint | 🟡 Medium |
152+
| Security permissions matrix | Object × Role × Permission visual table | 🟡 Medium |
153+
| Backward compatibility policy | Versioning strategy, deprecation timeline, SemVer guarantees | 🟡 Medium |
154+
155+
### 3.4 Guide Improvements
156+
157+
| Task | Details | Priority |
158+
|------|---------|----------|
159+
| Common patterns guide | Top 10 patterns: CRUD, search, pagination, auth, file upload, realtime, etc. | 🔴 High |
160+
| Troubleshooting / FAQ page | "My query returns empty" / "Validation fails but data looks correct" | 🟡 Medium |
161+
| Data flow diagram guide | How data moves from defineStack → kernel → driver → database | 🟡 Medium |
162+
| Plugin development tutorial | Step-by-step: create a plugin, register services, respond to hooks | 🟡 Medium |
163+
164+
### Phase 3 Checklist
165+
166+
- [ ] Create field type gallery page with all 46+ types
167+
- [ ] Create per-field-type configuration reference tables
168+
- [ ] Create error code catalog with 46 error codes
169+
- [ ] Create HTTP status mapping reference
170+
- [ ] Create protocol relationship diagram (visual)
171+
- [ ] Create query syntax cheat sheet
172+
- [ ] Add wire format JSON examples to protocol docs
173+
- [ ] Create common patterns guide (top 10 patterns)
174+
- [ ] Create troubleshooting / FAQ page
175+
- [ ] Create plugin development tutorial
176+
177+
---
178+
179+
## Phase 4: CLI & Tooling DX — 2 weeks
180+
181+
> **Goal:** The CLI is a developer's best friend — it catches mistakes before runtime.
182+
> **Metric:** `objectstack doctor` catches 90%+ of common configuration mistakes.
183+
184+
### 4.1 CLI Enhancements
185+
186+
| Task | Details | Priority |
187+
|------|---------|----------|
188+
| `objectstack diff` | Compare two spec versions, detect breaking changes, output changelog | 🔴 High |
189+
| `objectstack doctor` improvements | Detect: circular deps, missing test files, deprecated usage, unused objects, orphan views | 🔴 High |
190+
| `objectstack lint` | Style checker: snake_case names, required fields, label conventions | 🟡 Medium |
191+
| `objectstack explain <schema>` | Print human-readable explanation of any schema with examples | 🟡 Medium |
192+
| `objectstack migrate` | Auto-generate migration scripts for schema changes (add/remove fields) | 🟢 Low |
193+
194+
### 4.2 IDE Integration
195+
196+
| Task | Details | Priority |
197+
|------|---------|----------|
198+
| VSCode extension | Syntax highlighting, autocomplete, inline validation for `.object.ts`, `.view.ts`, etc. | 🔴 High |
199+
| JSON Schema for `objectstack.config.ts` | IDE autocomplete when editing config file | 🔴 High |
200+
| Diagnostic language server | Real-time validation with inline error squiggles | 🟡 Medium |
201+
| Code actions (quick fixes) | Auto-fix common issues: add missing `label`, fix snake_case, add required `options` | 🟡 Medium |
202+
203+
### 4.3 Code Generation
204+
205+
| Task | Details | Priority |
206+
|------|---------|----------|
207+
| `objectstack generate client --lang ts` | Type-safe client SDK from stack definition | 🟡 Medium |
208+
| `objectstack generate openapi` | OpenAPI spec from stack definition (already exists, ensure completeness) | 🟡 Medium |
209+
| `objectstack generate migration` | Database migration from object diff | 🟡 Medium |
210+
| `objectstack generate seed` | Generate seed data from object schemas | 🟢 Low |
211+
212+
### Phase 4 Checklist
213+
214+
- [ ] Implement `objectstack diff` with breaking change detection
215+
- [ ] Enhance `objectstack doctor` (circular deps, missing tests, deprecated usage)
216+
- [ ] Implement `objectstack lint` for naming conventions
217+
- [ ] Implement `objectstack explain` for schema documentation
218+
- [ ] Create VSCode extension with autocomplete and validation
219+
- [ ] Add JSON Schema for `objectstack.config.ts` IDE support
220+
- [ ] Implement `objectstack generate client` for typed SDK generation
221+
- [ ] Implement `objectstack generate migration` for schema diffs
222+
223+
---
224+
225+
## Phase 5: Studio as DX Hub — 3 weeks
226+
227+
> **Goal:** Studio becomes the visual IDE where developers design, test, and deploy without leaving the browser.
228+
> **Metric:** 80%+ of common CRUD apps can be built entirely in Studio.
229+
> **Dependency:** `apps/studio/ROADMAP.md` Phases 0–2.
230+
231+
### 5.1 Schema Designer
232+
233+
| Task | Details | Priority |
234+
|------|---------|----------|
235+
| Visual object builder | Drag-and-drop field creation with live preview | 🔴 High |
236+
| Field type picker | Visual catalog with previews (linked to Field Type Gallery) | 🔴 High |
237+
| Relationship visualizer | ERD-style diagram showing lookup/master-detail connections | 🟡 Medium |
238+
| Schema diff viewer | Side-by-side comparison of schema changes before apply | 🟡 Medium |
239+
240+
### 5.2 API Console
241+
242+
| Task | Details | Priority |
243+
|------|---------|----------|
244+
| Query builder UI | Visual filter/sort/field builder that generates QuerySchema JSON | 🔴 High |
245+
| Request/response history | Persistent history with replay, diff, and share capabilities | 🟡 Medium |
246+
| Mock data generator | Generate realistic test data based on field types | 🟡 Medium |
247+
248+
### 5.3 Code-Visual Bridge
249+
250+
| Task | Details | Priority |
251+
|------|---------|----------|
252+
| "Export as Code" button | Any visual design → generates `.object.ts` / `.view.ts` file | 🔴 High |
253+
| "Import from Code" | Paste `defineStack()` code → renders in Studio visual designer | 🟡 Medium |
254+
| Live sync with file system | Watch `.ts` files and reflect changes in Studio in real-time | 🟡 Medium |
255+
256+
### Phase 5 Checklist
257+
258+
- [ ] Implement visual object builder with drag-and-drop fields
259+
- [ ] Implement field type picker with live previews
260+
- [ ] Implement relationship ERD visualizer
261+
- [ ] Implement query builder UI with visual filters
262+
- [ ] Add request/response history to API console
263+
- [ ] Implement "Export as Code" for all visual designers
264+
- [ ] Implement "Import from Code" for defineStack() configs
265+
- [ ] Add live file sync between Studio and file system
266+
267+
---
268+
269+
## Phase 6: Ecosystem & Community — Ongoing
270+
271+
> **Goal:** Build a thriving ecosystem of plugins, examples, and community contributions.
272+
> **Metric:** 10+ community plugins published, 100+ GitHub stars.
273+
274+
### 6.1 Plugin Marketplace
275+
276+
| Task | Details | Priority |
277+
|------|---------|----------|
278+
| Plugin registry API | REST API for discovering, searching, and downloading plugins | 🟡 Medium |
279+
| Plugin quality scoring | Automated scoring: tests, docs, types, security scan | 🟡 Medium |
280+
| Plugin starter template | `objectstack generate plugin` with test setup, CI, publishing | 🔴 High |
281+
282+
### 6.2 Example Gallery
283+
284+
| Task | Details | Priority |
285+
|------|---------|----------|
286+
| 10+ curated examples | SaaS, eCommerce, Healthcare, Education, Project Management, etc. | 🟡 Medium |
287+
| Example difficulty rating | Beginner / Intermediate / Advanced badges | 🟡 Medium |
288+
| "Fork & Customize" flow | One-click fork of any example into user's own project | 🟢 Low |
289+
290+
### 6.3 Community Infrastructure
291+
292+
| Task | Details | Priority |
293+
|------|---------|----------|
294+
| Discord community | Developer support channel, showcase, RFC discussions | 🟡 Medium |
295+
| Blog / Changelog | Regular updates on new features, best practices, community highlights | 🟡 Medium |
296+
| Contributor recognition | Contributors page, "first PR" badges, hall of fame | 🟢 Low |
297+
298+
### Phase 6 Checklist
299+
300+
- [ ] Implement plugin registry API (search, publish, download)
301+
- [ ] Create plugin starter template with CI and publishing
302+
- [ ] Add plugin quality scoring system
303+
- [ ] Create 10+ curated example applications
304+
- [ ] Add example difficulty ratings
305+
- [ ] Set up Discord community with support channels
306+
- [ ] Create blog/changelog system for regular updates
307+
308+
---
309+
310+
## Timeline Summary
311+
312+
```
313+
2026 Q1–Q2 (DX Sprint)
314+
├── Phase 1: First Five Minutes [2 weeks] → Playground, scaffolding, quick-start
315+
├── Phase 2: Schema DX Helpers [2 weeks] → Factories, error messages, types
316+
└── Phase 3: Documentation & Reference [3 weeks] → Field gallery, error catalog, guides
317+
318+
2026 Q2–Q3 (Tooling Sprint)
319+
├── Phase 4: CLI & Tooling DX [2 weeks] → diff, doctor, lint, VSCode extension
320+
└── Phase 5: Studio as DX Hub [3 weeks] → Visual designer, code bridge
321+
322+
2026 Q3+ (Ecosystem Sprint)
323+
└── Phase 6: Ecosystem & Community [Ongoing] → Plugin marketplace, examples, community
324+
```
325+
326+
### Priority Matrix
327+
328+
| Impact ↓ / Effort → | Low (< 1 week) | Medium (1–2 weeks) | High (> 2 weeks) |
329+
|---------------------|-----------------|---------------------|-------------------|
330+
| **High Impact** | StackBlitz template, "How to Run" docs, Prerequisites check | `create-objectstack` wizard, Custom error map, Field type gallery | VSCode extension, Visual object builder |
331+
| **Medium Impact** | Query cheat sheet, Error code catalog, Export grouping comments | `objectstack diff`, `objectstack doctor`, Common patterns guide | Plugin marketplace, Live file sync |
332+
| **Lower Impact** | Branded types, Contributor page, Example ratings | Plugin starter template, Mock data generator | Diagnostic language server, Auto-migration |
333+
334+
---
335+
336+
## Success Criteria
337+
338+
| Metric | Current | Phase 1 | Phase 3 | Phase 6 |
339+
|--------|---------|---------|---------|---------|
340+
| Time to First App | ~30 min | < 5 min | < 5 min | < 3 min |
341+
| Documentation coverage | ~60% | 70% | 95% | 100% |
342+
| Interactive examples | 0 | 1 (StackBlitz) | 3+ | 10+ |
343+
| Community plugins | 0 | 0 | 2+ | 10+ |
344+
| CLI diagnostic commands | 2 | 4 | 6 | 8+ |
345+
| IDE autocomplete coverage | JSON Schema | JSON Schema + hints | VSCode extension | Language server |
346+
| Error message quality | Zod defaults | Custom error map | Full catalog | AI-assisted |
347+
| Helper functions (`define*`) | 1 (`defineStack`) | 4+ | 6+ | 6+ |
348+
| GitHub stars | — | 50+ | 200+ | 500+ |
349+
350+
---
351+
352+
## Relationship to Other Plans
353+
354+
| Document | Focus | Status |
355+
|----------|-------|--------|
356+
| `ROADMAP.md` | v3.0 spec hardening (Phases 5–11) | ✅ Complete |
357+
| `apps/studio/ROADMAP.md` | Studio IDE visual features (Phases 0–8) | 🔄 Active |
358+
| `packages/spec/DEVELOPMENT_PLAN.md` | Spec schema audit (Phases 1–4) | ✅ Complete |
359+
| **`DX_ROADMAP.md` (this file)** | **Developer Experience & Adoption** | 🆕 Active |
360+
361+
---
362+
363+
**Last Updated:** 2026-02-12
364+
**Maintainers:** ObjectStack Core Team
365+
**Status:** 🆕 Active — Phase 1 Ready to Start

0 commit comments

Comments
 (0)