|
| 1 | +# Migration Guide: `@object-ui/cli` → `@objectstack/plugin-ui` |
| 2 | + |
| 3 | +> **Date:** February 2026 |
| 4 | +> **Affects:** All users of the `objectui` CLI command |
| 5 | +
|
| 6 | +## Overview |
| 7 | + |
| 8 | +The ObjectUI CLI has been refactored from a standalone Commander.js-based CLI (`@object-ui/cli`) to an **oclif plugin** (`@objectstack/plugin-ui`). This enables integration with the unified ObjectStack CLI (`os`) ecosystem while maintaining full backward compatibility. |
| 9 | + |
| 10 | +## What Changed |
| 11 | + |
| 12 | +| Before | After | |
| 13 | +|--------|-------| |
| 14 | +| Package: `@object-ui/cli` | Package: `@objectstack/plugin-ui` | |
| 15 | +| Standalone bin: `objectui` | oclif plugin: auto-registered under `os ui` | |
| 16 | +| Commander.js-based | oclif Command classes | |
| 17 | +| `objectui dev` | `os ui dev` (preferred) or `objectui dev` (still works) | |
| 18 | + |
| 19 | +## Command Mapping |
| 20 | + |
| 21 | +All 15 commands are available under the `os ui` namespace: |
| 22 | + |
| 23 | +| Legacy Command | New Command | Status | |
| 24 | +|---------------|-------------|--------| |
| 25 | +| `objectui init` | `os ui init` | ✅ | |
| 26 | +| `objectui dev` | `os ui dev` | ✅ | |
| 27 | +| `objectui build` | `os ui build` | ✅ | |
| 28 | +| `objectui start` | `os ui start` | ✅ | |
| 29 | +| `objectui serve` | `os ui serve` | ✅ | |
| 30 | +| `objectui lint` | `os ui lint` | ✅ | |
| 31 | +| `objectui test` | `os ui test` | ✅ | |
| 32 | +| `objectui generate <type> <name>` | `os ui generate <type> <name>` | ✅ | |
| 33 | +| `objectui doctor` | `os ui doctor` | ✅ | |
| 34 | +| `objectui add <component>` | `os ui add <component>` | ✅ | |
| 35 | +| `objectui studio` | `os ui studio` | ✅ | |
| 36 | +| `objectui check` | `os ui check` | ✅ | |
| 37 | +| `objectui validate [schema]` | `os ui validate [schema]` | ✅ | |
| 38 | +| `objectui create plugin <name>` | `os ui create-plugin <name>` | ✅ | |
| 39 | +| `objectui analyze` | `os ui analyze` | ✅ | |
| 40 | + |
| 41 | +## Installation |
| 42 | + |
| 43 | +### With the unified ObjectStack CLI (recommended) |
| 44 | + |
| 45 | +```bash |
| 46 | +# Install the main CLI + UI plugin |
| 47 | +npm install -g @objectstack/cli @objectstack/plugin-ui |
| 48 | + |
| 49 | +# All UI commands are now available under `os ui` |
| 50 | +os ui dev |
| 51 | +os ui build |
| 52 | +os ui --help |
| 53 | +``` |
| 54 | + |
| 55 | +### Standalone (backward compatible) |
| 56 | + |
| 57 | +```bash |
| 58 | +# The objectui bin entry is preserved for backward compatibility |
| 59 | +npm install -g @objectstack/plugin-ui |
| 60 | + |
| 61 | +# Legacy commands still work |
| 62 | +objectui dev |
| 63 | +objectui build |
| 64 | +``` |
| 65 | + |
| 66 | +## Flag Changes |
| 67 | + |
| 68 | +Most flags are identical. The only notable differences: |
| 69 | + |
| 70 | +| Command | Old Flag | New Flag | Notes | |
| 71 | +|---------|----------|----------|-------| |
| 72 | +| `dev` | `-h, --host` | `-H, --host` | Short flag changed to avoid conflict with oclif's built-in `-h` (help) | |
| 73 | +| `serve` | `-h, --host` | `-H, --host` | Same as above | |
| 74 | +| `start` | `-h, --host` | `-H, --host` | Same as above | |
| 75 | + |
| 76 | +## Programmatic API |
| 77 | + |
| 78 | +The programmatic exports remain unchanged: |
| 79 | + |
| 80 | +```typescript |
| 81 | +import { serve, init } from '@objectstack/plugin-ui'; |
| 82 | + |
| 83 | +// These functions work exactly as before |
| 84 | +await serve('app.json', { port: '3000', host: 'localhost' }); |
| 85 | +await init('my-app', { template: 'dashboard' }); |
| 86 | +``` |
| 87 | + |
| 88 | +## Plugin Architecture |
| 89 | + |
| 90 | +The package now follows oclif plugin conventions: |
| 91 | + |
| 92 | +``` |
| 93 | +packages/cli/ |
| 94 | +├── src/ |
| 95 | +│ ├── cli.ts # Legacy Commander.js entry (backward compat) |
| 96 | +│ ├── index.ts # Programmatic exports |
| 97 | +│ ├── commands/ |
| 98 | +│ │ ├── serve.ts # Original command logic (unchanged) |
| 99 | +│ │ ├── dev.ts # Original command logic (unchanged) |
| 100 | +│ │ ├── ... # All 15 original command implementations |
| 101 | +│ │ └── ui/ # oclif Command classes |
| 102 | +│ │ ├── init.ts # → wraps commands/init.ts |
| 103 | +│ │ ├── dev.ts # → wraps commands/dev.ts |
| 104 | +│ │ ├── build.ts # → wraps commands/build.ts |
| 105 | +│ │ └── ... # All 15 oclif wrappers |
| 106 | +│ └── utils/ |
| 107 | +│ └── app-generator.ts # Shared utility (unchanged) |
| 108 | +└── package.json # oclif plugin config |
| 109 | +``` |
| 110 | + |
| 111 | +The `package.json` includes the oclif plugin declaration: |
| 112 | + |
| 113 | +```json |
| 114 | +{ |
| 115 | + "oclif": { |
| 116 | + "commands": "./dist/commands", |
| 117 | + "hooks": {} |
| 118 | + } |
| 119 | +} |
| 120 | +``` |
| 121 | + |
| 122 | +## Deprecation Timeline |
| 123 | + |
| 124 | +| Phase | Timeline | Details | |
| 125 | +|-------|----------|---------| |
| 126 | +| **Current** | Now | Both `objectui` and `os ui` work | |
| 127 | +| **Phase 1** | v4.0 | `objectui` shows deprecation warning | |
| 128 | +| **Phase 2** | v5.0 | `objectui` bin removed; `os ui` is the only entry | |
0 commit comments