shipcn

CLI to scaffold web projects by industry/vertical. Open-source, composition-first, non-destructive updates, SEO presets by page intent, provider adapters, design tokens, and full code ownership.

Yêu cầu: Node.js ≥18.

Cài đặt

git clone <repo>
cd shipcn
npm install
npm run build

Chạy CLI: node dist/cli/index.js <command> hoặc link global: npm link rồi dùng shipcn <command>.

Config và Registry

• Config: shipcn.config.json hoặc shipcn.config.yaml trong thư mục project. Các lệnh validate, generate, plan chỉ đọc JSON/YAML (không đọc .ts).
• Registry: Thư mục chứa manifest theo loại: industry/, provider/, theme/, page/, section/, feature/. Mặc định lấy từ trường registry trong config (đường dẫn tương đối với thư mục chứa config), hoặc ./registry. Có thể ghi đè bằng -r, --registry <path>.

Tạo project mới (init)

Tạo một Next.js project với industry, provider và theme.

Chế độ không hỏi (khuyến nghị):

# Tạo project trong thư mục hiện tại (cwd)
node dist/cli/index.js init -y --industry saas --provider local --theme default -r tests/fixtures/registry

# Tạo project trong thư mục chỉ định (ví dụ: web)
node dist/cli/index.js init -d web -y --industry saas --provider local --theme default -r tests/fixtures/registry

Lưu ý: Cần truyền -r, --registry trỏ tới thư mục registry có sẵn (ví dụ tests/fixtures/registry trong repo này). Init tạo ra shipcn.config.ts; nếu sau đó dùng validate / generate / plan, cần thêm file shipcn.config.json cùng nội dung (và thêm "registry": "./registry" nếu bạn copy registry vào project).

Sau khi init:

cd web
npm install
npm run dev

Mở http://localhost:3000.

Các lệnh chính

validate — Kiểm tra config và dependency

shipcn validate [-c shipcn.config.json] [-r ./registry] [--json]

• Kiểm tra config hợp lệ và resolve manifest (industry, feature, page, section, provider, theme).
• Mặc định: -c shipcn.config.json, registry lấy từ config hoặc ./registry.

generate — Sinh file từ config đã resolve

shipcn generate [-c shipcn.config.json] [-r ./registry] [-o .] [--dry-run] [--json]

• Đọc config + registry, resolve dependency, báo cáo/ghi file theo plan. -o là thư mục đích (mặc định .).

add-page — Thêm trang

shipcn add-page -r <route> -p <page-type> [-c config] [-r registry] [-d dir] [--add-to-nav] [--dry-run] [--json]

• Ví dụ: shipcn add-page -r contact -p landing (route /contact, page type landing).
• --add-to-nav: thử thêm vào navigation (marker-based).

add-section — Thêm section vào trang

shipcn add-section -p <page-route> -s <section-id> [--position top|bottom|before:id|after:id] [--variant id] [-c config] [-d dir] [--dry-run] [--json]

• Ví dụ: shipcn add-section -p about -s faq --position bottom.

add-feature — Thêm feature (pages, sections, providers, nav, SEO)

shipcn add-feature <feature-id> [-c config] [-r registry] [-d dir] [--dry-run]

• Ví dụ: shipcn add-feature contact, shipcn add-feature booking.

plan — Phân tích project và báo cáo gợi ý

shipcn plan [-c shipcn.config.json] [-r ./registry] [--json]

• Đọc config, routes, features, page composition, SEO scaffolding; đưa ra gợi ý (missing essentials, recommended upgrades, potential issues) kèm lệnh shipcn có thể chạy tiếp.
• --json: xuất báo cáo dạng JSON cho automation.

theme apply — Áp theme preset

shipcn theme apply <preset> [--preview] [--scope full|page:<route>|section:<id>] [-c config] [-r registry] [-d dir] [--json]

• Áp preset (token + section variant). --preview: chỉ xem thay đổi, không ghi file.

seo-sync — Đồng bộ SEO (metadata, structured data)

shipcn seo-sync [-c config] [-r registry] [-o outDir] [--dry-run] [--json]

switch-provider — Đổi data provider

shipcn switch-provider [--provider local-static|cloud-database] [-d dir] [-c config] [--dry-run] [--json]

upgrade — Thêm/đổi data provider (giữ hoặc nâng cấp)

shipcn upgrade [-d dir] [-c config] [--provider type] [--dry-run] [--json]

Workflow điển hình

1. Tạo project: shipcn init -d web -y --industry saas --provider local --theme default -r tests/fixtures/registry
2. Chạy app: cd web && npm install && npm run dev
3. Kiểm tra config (nếu dùng shipcn.config.json): shipcn validate -c web/shipcn.config.json -r web/registry
4. Sinh thêm file (nếu cần): shipcn generate -c web/shipcn.config.json -o web
5. Xem gợi ý cải thiện: shipcn plan -c web/shipcn.config.json (hoặc chạy trong thư mục web nếu đã có config tại đó)
6. Thêm trang/section/feature: dùng add-page, add-section, add-feature theo nhu cầu.

Development

npm install
npm run build
npm run test

Kiểm tra nhanh với fixture:

node dist/cli/index.js validate --config tests/fixtures/shipcn.config.json -r tests/fixtures/registry
node dist/cli/index.js plan --config tests/fixtures/shipcn.config.json -r tests/fixtures/registry

Tham khảo thêm

• Init: specs/002-init-scaffold/quickstart.md
• Plan (phân tích & gợi ý): specs/009-plan-command/quickstart.md
• Registry & config: specs/001-registry-config-engine/quickstart.md

Đóng gói và publish (npm / pnpm)

1. Cập nhật package.json: sửa version, repository.url (và name thành scope nếu dùng @your-scope/shipcn).
2. Đăng nhập: npm login hoặc pnpm login.
3. Build và đóng gói: npm run build (tự chạy trước khi publish nhờ prepublishOnly).
4. Publish:
   • npm: npm publish (public) hoặc npm publish --access restricted (scoped private).
   • pnpm: pnpm publish.

Gói publish gồm: dist/, README.md, registry/ (manifest mặc định). Người dùng sau khi cài có thể chạy init với registry đi kèm:

npx shipcn init -d myapp -y --industry saas --provider local --theme default -r ./node_modules/shipcn/registry

License

MIT (open-source).