Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (shipfolio) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

shipfolio

English | 中文

What is shipfolio?

A CLI tool that turns your local projects into a personal portfolio website. It scans your git repositories, uses your local AI tools (Claude Code, Codex, or v0) to generate a production-ready site, and deploys it to Cloudflare Pages or Vercel -- all in one command.

Built for developers who ship fast and need a way to showcase their work without spending hours on a portfolio.

Quick Start

npx shipfolio --scan ~/Projects

That's it. The tool walks you through everything interactively.

Prerequisites

Node.js >= 18
At least one AI engine installed locally:

Engine	Install	Notes
Claude Code	`npm install -g @anthropic-ai/claude-code`	Recommended. Best overall generation quality.
Codex	`npm install -g @openai/codex`	Alternative.
v0	Set `V0_API_KEY` env var	Best UI design quality. Requires paid v0 plan. Get your key at v0.dev.

Usage

1. Generate a New Site

# Interactive mode (recommended for first use)
npx shipfolio --scan ~/Projects

# Specify options upfront
npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal

The tool will:

Scan your directories for git repositories
Ask you to select which projects to include
Collect your personal info and design preferences
Generate the site using your local AI
Build and preview locally
Export a PDF version
Deploy to your chosen platform

Output directory: ./shipfolio-site/ (override with --output <dir>)

2. Update an Existing Site

npx shipfolio update --site ./shipfolio-site --scan ~/Projects

Detects new/changed/removed projects and applies incremental updates. Preserves your existing design, layout, and any custom modifications.

3. Generate Spec Only (for Use Inside AI Sessions)

If you're already inside a Claude Code or Codex session:

npx shipfolio spec --scan ~/Projects --output ./

Outputs shipfolio-spec.json and shipfolio-prompt.md. Feed the prompt to your current AI session to generate the site directly.

4. Deploy an Existing Site

npx shipfolio deploy --site ./shipfolio-site --platform cloudflare
npx shipfolio deploy --site ./shipfolio-site --platform vercel

5. Export PDF

npx shipfolio pdf --site ./shipfolio-site

Requires Playwright browsers: npx playwright install chromium

6. Preview Locally

npx shipfolio preview --site ./shipfolio-site

All Commands

Command	Description
`shipfolio` / `shipfolio init`	Generate a new portfolio site (interactive)
`shipfolio update --site <path>`	Update an existing site with new projects
`shipfolio spec --output <dir>`	Generate spec + prompt files only
`shipfolio deploy --site <path>`	Deploy a built site
`shipfolio pdf --site <path>`	Export site to PDF
`shipfolio preview --site <path>`	Start local preview server

All Flags

Flag	Values	Default
`--scan <dir>`	Any directory path (repeatable)	Current directory
`--engine <name>`	`claude` / `codex` / `v0`	Auto-detect
`--deploy <platform>`	`cloudflare` / `vercel` / `local`	Prompted
`--style <theme>`	`dark-minimal` / `light-clean` / `monochrome`	Prompted
`--accent <hex>`	Hex color, e.g. `#7c3aed`	Prompted
`--output <dir>`	Output directory path	`./shipfolio-site`
`--auto`	Skip all prompts, use defaults	`false`
`--no-pdf`	Skip PDF export	`false`
`--no-preview`	Skip local preview	`false`

Generated Site

The output is a standard Next.js 15 project:

Next.js 15 (App Router) with static export
Tailwind CSS v4
shadcn/ui components
TypeScript
Responsive (desktop + tablet + mobile)
Print-optimized CSS for PDF export

Build output is a static out/ directory deployable anywhere.

Deployment

Cloudflare Pages

The tool runs wrangler pages deploy under the hood. On first run it opens a browser for authentication. Your site gets a <project-name>.pages.dev URL.

Free tier: unlimited sites, 500 builds/month, unlimited bandwidth.

Vercel

The tool runs vercel deploy --prod. On first run it opens a browser for authentication. Your site gets a <project-name>.vercel.app URL.

GitHub Auto-Deploy

After initial deployment, the tool optionally sets up a GitHub repo. Connect it to Cloudflare Pages or Vercel for push-to-deploy.

Project Structure

shipfolio/
  src/
    scanner/       -- Git repo detection, tech stack extraction
    interviewer/   -- Interactive CLI prompts
    spec/          -- Spec builder, diff computation
    orchestrator/  -- AI engine dispatch (Claude/Codex/v0)
    deployer/      -- Cloudflare Pages, Vercel, GitHub
    pdf/           -- Playwright PDF export
    commands/      -- CLI command handlers
    utils/         -- Logger, exec, fs helpers
  prompts/         -- AI prompt templates
  bin/             -- CLI entry point

License

MIT

shipfolio 是什么?

一个 CLI 工具，将你本地的项目转化为个人作品集网站。它扫描你的 git 仓库，使用你本地的 AI 工具（Claude Code、Codex 或 v0）生成生产级网站，并一键部署到 Cloudflare Pages 或 Vercel。

为快速交付项目但没时间做作品集的开发者而建。

快速开始

npx shipfolio --scan ~/Projects

工具会以交互方式引导你完成所有步骤。

前置条件

Node.js >= 18
至少安装一个 AI 引擎:

引擎	安装方式	说明
Claude Code	`npm install -g @anthropic-ai/claude-code`	推荐。综合生成质量最佳。
Codex	`npm install -g @openai/codex`	备选。
v0	设置 `V0_API_KEY` 环境变量	UI 设计质量最佳。需要 v0 付费订阅。在 v0.dev 获取 API key。

使用方法

1. 生成新网站

# 交互模式（首次使用推荐）
npx shipfolio --scan ~/Projects

# 预设参数
npx shipfolio --scan ~/Projects --engine claude --deploy cloudflare --style dark-minimal

工具流程:

扫描指定目录中的 git 仓库
让你选择要展示的项目
收集个人信息和设计偏好
调用本地 AI 生成网站
本地构建并预览
导出 PDF 版本
部署到选定平台

输出目录: ./shipfolio-site/（可通过 --output <dir> 修改）

2. 更新已有网站

npx shipfolio update --site ./shipfolio-site --scan ~/Projects

检测新增/变更/移除的项目，增量更新。保留现有设计、布局和所有自定义修改。

3. 仅生成 Spec（在 AI 会话中使用）

如果你已经在 Claude Code 或 Codex 会话中:

npx shipfolio spec --scan ~/Projects --output ./

输出 shipfolio-spec.json 和 shipfolio-prompt.md。将 prompt 输入当前 AI 会话即可直接生成网站。

4. 部署已有网站

npx shipfolio deploy --site ./shipfolio-site --platform cloudflare
npx shipfolio deploy --site ./shipfolio-site --platform vercel

5. 导出 PDF

npx shipfolio pdf --site ./shipfolio-site

需要 Playwright 浏览器: npx playwright install chromium

6. 本地预览

npx shipfolio preview --site ./shipfolio-site

所有命令

命令	说明
`shipfolio` / `shipfolio init`	生成新的作品集网站（交互式）
`shipfolio update --site <path>`	用新项目更新已有网站
`shipfolio spec --output <dir>`	仅生成 spec + prompt 文件
`shipfolio deploy --site <path>`	部署已构建的网站
`shipfolio pdf --site <path>`	将网站导出为 PDF
`shipfolio preview --site <path>`	启动本地预览服务器

所有参数

参数	可选值	默认值
`--scan <dir>`	任意目录路径（可重复）	当前目录
`--engine <name>`	`claude` / `codex` / `v0`	自动检测
`--deploy <platform>`	`cloudflare` / `vercel` / `local`	交互选择
`--style <theme>`	`dark-minimal` / `light-clean` / `monochrome`	交互选择
`--accent <hex>`	Hex 颜色值，如 `#7c3aed`	交互选择
`--output <dir>`	输出目录路径	`./shipfolio-site`
`--auto`	跳过所有提示，使用默认值	`false`
`--no-pdf`	跳过 PDF 导出	`false`
`--no-preview`	跳过本地预览	`false`

生成的网站

输出是标准的 Next.js 15 项目:

Next.js 15 (App Router) 静态导出
Tailwind CSS v4
shadcn/ui 组件
TypeScript
响应式设计（桌面端 + 平板 + 移动端）
针对 PDF 导出优化的打印样式

构建输出为纯静态的 out/ 目录，可部署到任何静态托管平台。

部署说明

Cloudflare Pages

工具内部调用 wrangler pages deploy。首次运行会打开浏览器进行认证。网站获得 <项目名>.pages.dev 域名。

免费额度: 无限站点，500 次构建/月，无限带宽。

Vercel

工具内部调用 vercel deploy --prod。首次运行会打开浏览器进行认证。网站获得 <项目名>.vercel.app 域名。

GitHub 自动部署

初始部署后，工具可选择性地创建 GitHub 仓库。将仓库连接到 Cloudflare Pages 或 Vercel 即可实现 push 自动部署。

许可证

MIT

shipfolio

Package Exports

Readme

shipfolio

What is shipfolio?

Quick Start

Prerequisites

Usage

1. Generate a New Site

2. Update an Existing Site

3. Generate Spec Only (for Use Inside AI Sessions)

4. Deploy an Existing Site

5. Export PDF

6. Preview Locally

All Commands

All Flags

Generated Site

Deployment

Cloudflare Pages

Vercel

GitHub Auto-Deploy

Project Structure

Links

License

shipfolio 是什么?

快速开始

前置条件

使用方法

1. 生成新网站

2. 更新已有网站

3. 仅生成 Spec（在 AI 会话中使用）

4. 部署已有网站

5. 导出 PDF

6. 本地预览

所有命令

所有参数

生成的网站

部署说明

Cloudflare Pages

Vercel

GitHub 自动部署

相关链接

许可证