-
Notifications
You must be signed in to change notification settings - Fork 1
docs: add DX Roadmap for post-v3.0 developer experience improvements #641
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,365 @@ | ||||||
| # ObjectStack — Developer Experience (DX) Roadmap | ||||||
|
|
||||||
| > **Date:** 2026-02-12 | ||||||
| > **Scope:** Post v3.0 — Focused entirely on Developer Experience | ||||||
| > **Based On:** Full codebase scan + documentation audit (171 schemas, 191 test files, 40+ doc pages, 4 examples, 19 packages) | ||||||
| > **Previous:** `ROADMAP.md` (v3.0 Phases 5–11 ✅ Complete) | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Executive Summary | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| ### Current DX Assessment | ||||||
|
|
||||||
| | Area | Score | Notes | | ||||||
| |------|-------|-------| | ||||||
| | **Type Safety** | ⭐⭐⭐⭐⭐ | Zod-first, 7,095+ `.describe()`, full inference | | ||||||
| | **Schema Completeness** | ⭐⭐⭐⭐⭐ | 171 schemas, 1,470 JSON Schemas, OpenAPI 3.1 | | ||||||
| | **Test Coverage** | ⭐⭐⭐⭐⭐ | 191 test files, 5,157+ tests | | ||||||
| | **IDE Autocomplete** | ⭐⭐⭐⭐ | Bundled `objectstack.json`, `.describe()` tooltips | | ||||||
| | **Getting Started** | ⭐⭐⭐ | Docs exist but no interactive playground | | ||||||
| | **Error Messages** | ⭐⭐⭐ | Zod defaults + some custom refinements | | ||||||
| | **Helper Functions** | ⭐⭐⭐ | `Field.*` excellent; `ObjectSchema.create()`, `defineStack()` minimal | | ||||||
| | **Reference Docs** | ⭐⭐⭐ | API docs generated but no field type gallery or error code reference | | ||||||
| | **Examples** | ⭐⭐⭐ | 4 examples but missing "How to Run" instructions | | ||||||
| | **Migration Story** | ⭐⭐ | V3 guide exists but no automated `codemod` tooling | | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Phase 1: First Five Minutes (Onboarding) — 2 weeks | ||||||
|
|
||||||
| > **Goal:** A new developer runs `npx create-objectstack` and has a working app in under 5 minutes. | ||||||
| > **Metric:** Time from `npm init` → running app with CRUD UI < 5 min. | ||||||
|
|
||||||
| ### 1.1 Interactive Playground | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | StackBlitz starter template | Pre-configured `app-todo` example on StackBlitz with "Open in Editor" button | 🔴 High | | ||||||
| | "Try Online" button in README | One-click link in `packages/spec/README.md` and docs site | 🔴 High | | ||||||
| | CodeSandbox template | Alternative playground for CodeSandbox users | 🟡 Medium | | ||||||
|
|
||||||
| ### 1.2 Quick-Start Improvements | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | Prerequisites check page | Add Node 18+, pnpm requirement callouts to getting-started/index.mdx | 🔴 High | | ||||||
| | "How to Run" in every example | Add copy-paste commands + expected output to each example README | 🔴 High | | ||||||
| | First-run troubleshooting guide | Common issues: pnpm install fails, port conflicts, TypeScript version | 🟡 Medium | | ||||||
| | 5-minute video walkthrough | Screen recording of `create-objectstack` → running app | 🟡 Medium | | ||||||
|
|
||||||
| ### 1.3 `create-objectstack` Scaffolding | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | Interactive project wizard | `npx create-objectstack` with prompts: name, template, driver, framework | 🔴 High | | ||||||
| | Template: Minimal API | Server + memory driver + 1 object + REST API | 🔴 High | | ||||||
| | Template: Full-Stack | Server + UI + auth + 3 objects (CRM-lite) | 🟡 Medium | | ||||||
| | Template: Plugin | Bare plugin skeleton with test setup | 🟡 Medium | | ||||||
|
|
||||||
| ### Phase 1 Checklist | ||||||
|
|
||||||
| - [ ] Create StackBlitz starter template from `app-todo` | ||||||
| - [ ] Add "Try Online" button to spec README.md and docs site hero | ||||||
| - [ ] Add "How to Run" section to each example README (app-todo, app-crm, app-host) | ||||||
| - [ ] Add prerequisites section to getting-started docs | ||||||
| - [ ] Create first-run troubleshooting page | ||||||
| - [ ] Implement `create-objectstack` CLI wizard with 3 templates | ||||||
| - [ ] Record 5-minute getting-started video | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Phase 2: Schema DX Helpers — 2 weeks | ||||||
|
|
||||||
| > **Goal:** Make defining objects, views, and flows feel as natural as writing a React component. | ||||||
| > **Metric:** Lines of code to define a complete CRUD object < 20 LOC. | ||||||
|
|
||||||
| ### 2.1 Enhanced Factory Functions | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | `ObjectSchema.create()` with defaults | Auto-generate `label` from `name`, merge common fields (id, created_at, updated_at), validate fields | 🔴 High | | ||||||
| | `defineView()` helper | Type-safe view builder: `defineView({ object: 'task', type: 'grid', columns: [...] })` | 🔴 High | | ||||||
| | `defineApp()` helper | Type-safe app builder: `defineApp({ name: 'crm', navigation: [...] })` | 🟡 Medium | | ||||||
| | `defineFlow()` helper | Type-safe flow builder: `defineFlow({ trigger: 'record_create', steps: [...] })` | 🟡 Medium | | ||||||
| | `defineAgent()` helper | Type-safe agent builder: `defineAgent({ role: 'support', tools: [...] })` | 🟡 Medium | | ||||||
|
|
||||||
| ### 2.2 Improved Validation Error Messages | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | Custom Zod error map for ObjectStack | Contextual errors: "Field 'status' has type 'select' but is missing required 'options' property" | 🔴 High | | ||||||
| | Actionable error suggestions | Include "Did you mean?" suggestions for common typos (e.g., `text_area` → `textarea`) | 🟡 Medium | | ||||||
| | Validation error formatter | Pretty-print validation errors with path highlighting for CLI output | 🟡 Medium | | ||||||
| | Schema-aware diagnostics | Custom refinements that check cross-field consistency (e.g., lookup requires `reference`) | 🟡 Medium | | ||||||
|
|
||||||
| ### 2.3 Type-Safe Patterns | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | Branded types for identifiers | `ObjectName`, `FieldName`, `ViewName` branded types for compile-time safety | 🟡 Medium | | ||||||
| | Strict mode for `defineStack()` | Optional strict mode that validates all cross-references (e.g., view references valid object) | 🟡 Medium | | ||||||
| | Generic type parameters | `defineStack<Objects>()` that infers object names for type-safe view.object references | 🟢 Low | | ||||||
|
|
||||||
| ### Phase 2 Checklist | ||||||
|
|
||||||
| - [ ] Enhance `ObjectSchema.create()` with auto-label, common fields, and validation | ||||||
| - [ ] Implement `defineView()` with column type inference | ||||||
| - [ ] Implement `defineApp()` with navigation builder | ||||||
| - [ ] Implement `defineFlow()` with step type inference | ||||||
| - [ ] Create custom Zod error map with contextual messages | ||||||
| - [ ] Add "Did you mean?" suggestions for FieldType typos | ||||||
| - [ ] Create pretty-print validation error formatter for CLI | ||||||
| - [ ] Add branded types for ObjectName, FieldName, ViewName | ||||||
| - [ ] Add strict cross-reference validation mode to `defineStack()` | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| ## Phase 3: Documentation & Reference — 3 weeks | ||||||
|
|
||||||
| > **Goal:** Every schema has a visual reference page; every error has a documented solution. | ||||||
| > **Metric:** 100% of user-facing schemas have a dedicated reference page with examples. | ||||||
|
|
||||||
| ### 3.1 Field Type Gallery | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | Visual field type reference | Interactive page showing all 46+ field types with live previews | 🔴 High | | ||||||
| | Field configuration reference | Per-type property tables (text: maxLength, pattern; number: min, max, precision) | 🔴 High | | ||||||
| | Field type decision tree | "Which field type should I use?" interactive guide | 🟡 Medium | | ||||||
| | Field validation rules per type | Default validation behavior for each field type | 🟡 Medium | | ||||||
|
|
||||||
| ### 3.2 Error & Status Code Reference | ||||||
|
|
||||||
| | Task | Details | Priority | | ||||||
| |------|---------|----------| | ||||||
| | Error code catalog | All 46 error codes with descriptions, causes, and fixes | 🔴 High | | ||||||
|
||||||
| | Error code catalog | All 46 error codes with descriptions, causes, and fixes | 🔴 High | | |
| | Error code catalog | Catalog of all StandardErrorCode values with descriptions, causes, and fixes | 🔴 High | |
Copilot
AI
Feb 12, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Checklist item says "46+ types", but the current FieldType enum has 44 values. Suggest updating this to the actual count or wording it to avoid hardcoding a number.
Suggested change
| - [ ] Create field type gallery page with all 46+ types | |
| - [ ] Create field type gallery page with all defined field types |
Copilot
AI
Feb 12, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Checklist item says "46 error codes", but StandardErrorCode currently contains 51 entries. Please update the count or wording so it matches the spec.
Suggested change
| - [ ] Create error code catalog with 46 error codes | |
| - [ ] Create error code catalog for all standard error codes |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This claims there are "46+" field types, but
packages/spec/src/data/field.zod.tscurrently defines 44 values in theFieldTypeenum. Consider updating the count (or referencing the enum directly so the roadmap doesn’t go stale).