@fluid-app/fluid-cli-theme-dev

中文文档
0.1.1226发布于 2026/11/17TypeScriptES Module近 30 天下载 20万

Fluid CLI plugin for theme developer workflows — dev server, push, pull, init, crawl, compare

原始使用文档
文档目录23 节
  1. Installation
  2. Authentication
  3. Commands
  4. fluid theme dev
  5. Member sites
  6. fluid theme push
  7. fluid theme pull
  8. fluid theme widget
  9. fluid theme init
  10. fluid theme navigate
  11. fluid theme skills install
  12. fluid theme crawl <url>
  13. fluid theme compare
  14. Theme Directory Structure
  15. Remote binary assets
  16. Member sites (retired)
  17. Native widgets
  18. Staging
  19. Publishing when a teammate published first
  20. Taking a teammate's staging changes
  21. Promoting staging to live
  22. Comparing with staging
  23. Development

@fluid-app/fluid-cli-theme-dev

Fluid CLI plugin for theme development. Adds fluid theme commands for local dev server, push, pull, scaffolding, and page-clone evidence (crawl / compare).

Installation

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-theme-dev

Requires @fluid-app/fluid-cli as the core CLI.

Authentication

Log in before using any theme commands:

fluid login

Commands

fluid theme dev

Start a local dev server that proxies your storefront with hot reload:

fluid theme dev

The dev server will:

  1. Create (or reuse) an isolated development theme
  2. Preserve pulled binary assets as ImageKit URL references without downloading or re-uploading their bytes
  3. Keep editable source files (Liquid, CSS, JS, SVG, JSON) locally
  4. Upload a newly added binary once, save its ImageKit URL reference, and remove its local bytes
  5. Watch for source-file changes and sync them automatically
  6. Proxy requests to {company}.fluid.app with local file overrides

For a pulled theme, a newly created dev theme is a server-side reference clone of the pulled source. It preserves theme content and DAM/ImageKit references, so initial dev startup does not reseed every asset from the working copy. The CLI keeps a compact local index of the development theme's acknowledged checksums and version. Later startups validate that version, compare local files to the cached dev state, and send only the actual changes without downloading the complete remote resource index. A web-editor write, changed ImageKit manifest, missing or malformed cache, or interrupted write invalidates the shortcut and falls back to the full remote comparison. Set FLUID_THEME_DEV_DISABLE_SHADOW_SYNC=1 to force that comparison as an emergency rollback.

Theme paths that differ only by letter case are refused before pull, push, or dev writes. Windows separators are normalized before comparison. Default macOS and Windows filesystems cannot preserve both resources, so continuing would replace one path and delete the other.

FlagDefaultDescription
--host <host>127.0.0.1Local server host
--port <port>9292Local server port
-t, --theme <name-or-id>autoUse a specific theme instead of dev theme
--live-reload <mode>full-pageReload mode: full-page or off
--navigateoffOpen browser navigator after start
--root <path>.Theme root directory

Member sites

Theme member sites are retired. Member sites are built with Sites now: fluid sites (fluid member-site). fluid theme no longer syncs members_sites.json, config/members_sites.json or members_page/**, and fluid theme dev has no /_members preview. See Member sites (retired).

fluid theme push

Upload local theme files to a remote theme:

fluid theme push                        # Interactive theme selection
fluid theme push --theme "My Theme"     # By name
fluid theme push --theme 42             # By ID
fluid theme push --publish              # Push and publish
fluid theme push --nodelete             # Keep remote files not present locally
fluid theme push --auto-baseline        # First push without a baseline: record
                                        # the server's current state as the
                                        # baseline, then push only local diffs

Pushing into an existing theme requires a local baseline (recorded by pull, or migrated from a checksum-era .fluid-theme.json). Without one, push refuses so it can't silently clobber the server. --auto-baseline instead records the server's current state as the baseline — no local file is modified, files identical to the server aren't re-uploaded, and files that exist only on the server are never deleted — then pushes what differs locally. Mist Desktop's one-click Publish uses this flag.

Files containing unresolved <<<<<<< / ======= / >>>>>>> conflict markers are never uploaded; push lists them and exits (with a machine-readable FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=… line under --auto-baseline).

fluid theme pull

Download a remote theme to your local directory:

fluid theme pull                        # Interactive theme selection
fluid theme pull --theme "My Theme"     # By name or ID
fluid theme pull --nodelete             # Keep local files not present on remote
fluid theme pull --resolve remote       # Auto-resolve conflicts to the server's
                                        # side (or `--resolve local` to keep
                                        # yours) instead of writing markers

By default, conflicting edits (changed locally and on the server since the last sync) are written with git-style conflict markers for you to resolve. For non-interactive use, --resolve local keeps your side of each conflicting hunk and --resolve remote takes the server's; before any auto-resolution overwrites local content, the pre-merge working tree is committed to the theme's shadow history (.fluid-theme/repo) so the discarded side stays restorable.

fluid theme widget

Customize a Fluid native widget ({% section 'fluid://native/widgets/<key>' %}) through the theme's own copy of it. The copy replaces the widget at every placement in the theme, the same copy the visual builder makes when a widget is dropped:

fluid theme widget copy acct            # Make the copy and pull it into fluid_native_acct/ (asks first on the live theme)
fluid theme widget copy acct --yes      # Same, without the live-theme confirmation
fluid theme widget reset acct           # Delete the copy and its fluid_native_acct/ folder (asks first)
fluid theme widget reset acct --yes     # Same, without the confirmation

A copy keeps the template type of Fluid's original, so it is pulled into sections/fluid_native_<key>/ for a widget that is still a section and into widgets/fluid_native_<key>/ for one stored as a widget. reset deletes the theme's copy of either type and removes both folders.

Both commands act on the theme in .fluid-theme.json unless --theme <id> is passed, then run an ordinary fluid theme pull of that theme so the sync baseline matches the server. The pull also brings down any other changes made to the theme since the last pull.

On the live (active) theme a copy or reset changes what members see as soon as it is made, so copy asks before it makes the copy there and reset says the theme is live in its confirmation. --yes skips both prompts.

Do not create sections/fluid_native_<key>/ or widgets/fluid_native_<key>/ by hand: without a copy of that type, a push makes it a plain template that replaces nothing, and every placement keeps rendering Fluid's original. fluid theme push warns about such folders.

fluid theme init

Scaffold a new theme from the base template:

fluid theme init my-theme
cd my-theme
fluid theme dev

fluid theme navigate

Interactively select a route and open it in the browser (requires a running dev server):

fluid theme navigate

fluid theme skills install

Copy the bundled theme AI skills (e.g. themes-review) into the current directory so an agent can load them. Defaults to .agents/skills/, the tool-neutral convention for agent skills:

fluid theme skills install                      # → .agents/skills/
fluid theme skills install --dir .claude/skills # custom location
fluid theme skills install --force              # overwrite existing skills without prompting

Existing skills are left untouched unless you confirm the overwrite (or pass --force).

fluid theme crawl <url>

Scrape a public page through Fluid's managed browser (JavaScript rendered) and print JSON with its Markdown, optional HTML, and a hosted screenshot URL. Mist's agent runs this command for every crawl.

fluid theme crawl https://example.com/                          # Markdown, main content only
fluid theme crawl https://example.com/ --format html --format screenshot
fluid theme crawl https://example.com/ \
  --viewport 1440x900 --full-page --quality 90 --no-main-content-only \
  --evidence .                                                  # durable page-clone bundle
fluid theme crawl https://example.com/ \
  --action '{"type":"click","selector":"#accept-cookies"}' \
  --action '{"type":"wait","milliseconds":1000}'               # act before the capture
OptionMeaning
--format <f>markdown, html, or screenshot; repeatable or comma-separated. Default markdown, or all three with --evidence
--viewport WxHExact CSS-pixel viewport (implies a screenshot). Use 1440x900 and 390x844 for desktop/mobile parity
--full-pageCapture the complete document height
--quality <1-100>Screenshot quality
--no-main-content-onlyKeep the nav, announcement bar, and footer. Use it for site cloning
--evidence <dir>Save an evidence bundle under <dir>/.mist-desktop/source-baselines/. Requires --viewport
--action <json>A browser action before the evidence walk: {"type":"wait","milliseconds":N} (up to 10000), {"type":"click","selector":"…"}, or {"type":"scroll","direction":"up|down"}. Repeatable, up to 8
--post-evidence-action <json>An action after the evidence walk and before the final screenshot, e.g. to close a drawer the walk opened. Also accepts {"type":"dismiss","selector":"…","scope_selector":"…"}, which the sidecar records. Needs --evidence and --full-page. Repeatable, up to 8
--directSkip Fluid's endpoint and call Firecrawl with your own FIRECRAWL_API_KEY

--evidence writes the bundle in the layout Mist's compare_preview_to_source reads, so either Mist or fluid theme compare can compare it: the full screenshot, the Markdown/HTML, the raw HTML, the page's own CSS, and a .page-evidence.json sidecar with landmarks, computed styles, SHA-256 hashes, and receipts. The JSON output lists every path (evidence.files). Inline content is capped at about 200KB, or a 16KB excerpt when the full documents are saved. The scrape times out after 60s. With --evidence, stylesheet recovery is bounded at 30s and the screenshot download at 20s. Both downloads refuse localhost and private-network addresses.

Where the crawl runs. The CLI calls Fluid's crawl endpoint with your fluid login token, so you do not need a Firecrawl key. If the endpoint is not deployed on your API host (HTTP 404) or not configured (HTTP 503), and FIRECRAWL_API_KEY is set, the CLI falls back to Firecrawl directly with that key. Create a key at https://www.firecrawl.dev/app/api-keys. Errors are printed as JSON ({"ok": false, "error": {"code": …, "message": …}}), and the command exits 1.

fluid theme compare

Render the local fluid theme dev preview at a crawl bundle's exact viewport. It prints the same banded pixel diff Mist's compare_preview_to_source reports: a bands[] array and a worst-first summary, with exact-copy and media-parity checks.

fluid theme dev &                                   # serves http://127.0.0.1:9292
fluid theme compare --source .                      # newest "/" capture in ./.mist-desktop/source-baselines
fluid theme compare --source .mist-desktop/source-baselines/<file>.page-evidence.json \
  --route /collections/all --geometry diagnostic --media diagnostic
OptionDefaultMeaning
--source <path>(required)A .page-evidence.json sidecar, its directory, or the --evidence dir
--route <path>/Local route to render
--source-route <path>--routeSource pathname when it differs (for example /en-us for /)
--url <url>http://127.0.0.1:9292Base URL of the running preview
--mode full|viewportfullWhole page, or the top viewport only
--copy exact|diagnosticexactexact fails on any ordered rendered-copy mismatch
--geometry strict|diagnosticstrictstrict fails when document height differs by more than 5%
--media strict|diagnosticstrictstrict fails on image/video parity differences
--viewport WxHPick the capture at this viewport when --source holds several

The command refuses mixed captures, silent resizing, failed routes, truncation, horizontal overflow, unresolved media, and copy mismatches. On a refusal, ok is false and the command exits 1. A successful run means the evidence is available. It does not mean the page passes visually. Fix the worst band, then compare again. The local capture is saved under .mist-desktop/screenshots/.

compare needs a headless browser. Playwright is an optional peer dependency, so a theme-dev install never downloads browsers. Install it once with:

npm i -g playwright && npx playwright install chromium

Theme Directory Structure

A valid theme directory must contain at least one of: templates/, assets/, config/, or the asset reference manifest .fluid-assets.json.

Use a .fluidignore file (same syntax as .gitignore) to exclude files from syncing.

Remote binary assets

fluid theme pull keeps binary assets such as images, fonts, video, and PDFs remote rather than downloading them into assets/. Their ImageKit URL reference metadata is recorded in .fluid-assets.json. The CLI uses that manifest when it starts a dev theme or pushes to another theme, so existing asset_url calls continue to resolve normally without local binary copies.

When a developer adds a new binary file during fluid theme dev, the CLI uploads it once, records its ImageKit URL reference in the manifest, and removes its local bytes after the theme resource has been saved. A later fluid theme push writes that same ImageKit URL into the selected target theme without a second binary upload.

Binary assets must be direct children of assets/ (for example, assets/logo.png); nested asset directories are not supported by the theme resource API.

Do not add .fluid-assets.json to .fluidignore; it is already excluded from theme uploads and file watching. Commit it with the theme source so every developer receives the same remote asset references.

Member sites (retired)

Theme member sites (members_sites.json at the theme root or under config/, and members_page/<name>/ templates) are retired. Build member sites with Sites instead: fluid sites (fluid member-site).

fluid theme skips these files in every direction and prints a warning that names them:

  • push, dev and staging publish never upload them, and never delete Fluid's copies, so member pages already on Fluid keep serving to members.
  • pull and staging pull never write them; local copies are left alone.
  • staging compare neither declares them nor counts them as a difference.
  • lint lists them as warnings and does not check them.

You can delete the local files once your member site lives in Sites.

Native widgets

{% section 'fluid://native/widgets/<key>', id: '…' %} places a Fluid-owned widget. It has no local file; fluid theme lint accepts known keys and warns about unknown ones. Placing a new native widget needs the company to have member sites enabled.

To customize a widget, create the theme's own copy with POST /api/v202604/themes/<id>/native-widget-copies and {"native_widget_key": "<key>"}. The copy replaces the widget at every placement in that theme, and a later pull brings it down as sections/fluid_native_<key>/index.liquid. Don't create that file by hand: a hand-written sections/fluid_native_<key> is a plain section and does not replace the widget.

Staging

Retired template types (account_page, members_dashboard and members_login) are not theme files: their folders are never uploaded, published or listed.

Publishing when a teammate published first

fluid theme staging publish sends every theme file it publishes (all but the paths it skips and lists, such as files attached to a template), so it would put this checkout's copy of each of those back on staging. To keep that from undoing a teammate's work by accident, each successful publish records the staging revision and the files it published in .fluid-theme/staging-baseline.json. The next publish from the same directory compares staging with that record first. When files changed on staging since then and this checkout has them differently, the publish is refused with staging_moved, names those files and the current revision, and changes nothing:

Staging has changes you don't have (revision 12). Publishing would replace them. Get those changes first, or publish with --force to replace them.
  - sections/hero_section/index.liquid
  • Bring their changes into this checkout and publish again; once your copies match staging's, nothing is replaced and the check passes.
  • --replace-at <revision> replaces them on purpose, only while staging is still at that revision. If someone published again meanwhile, the check runs again and names the new files. Mist's Replace anyway uses this.
  • --force replaces them whatever the revision.

Paths are matched however a resource's path is spelled, so a case or resource-kind difference doesn't hide a file. With no record (a new checkout, or the file deleted), there is nothing to compare and the publish isn't checked. With --json, the refusal's error.type is staging_moved and error.paths lists the files.

Taking a teammate's staging changes

fluid theme staging pull writes into this directory the files someone else published to staging since this directory last published, so the next publish carries their work instead of being refused. It only writes files this directory still has as they were at that publish; a file you changed too is kept and named, never overwritten. Staging names its own copies of the menus, so a file taken from staging has each one put back to the menu this directory names in the same place (matched through the legacy members_sites.json menu references, when both sides still have one); a file that would still name a staging menu is kept. Retired member site files are never taken. When the directory then matches staging, its staging record moves to the current revision. With --json it prints revision, taken, kept (each with its reason), matches, and verified (false when the closing comparison with staging couldn't be made, so matches is unconfirmed).

Promoting staging to live

fluid theme staging promote copies exactly what staging serves onto the live theme, all at once. It lists the files it will write and remove and asks first; pass --yes to skip the question (JSON mode always needs --yes). It only promotes when the live theme hasn't changed since staging was based on it; otherwise it refuses rather than overwrite that change. Images and other binary files are copied to assets the live theme owns.

fluid theme staging undo-promote puts the live theme back as it was before the latest promotion, while the live theme still serves exactly what that promotion applied.

Comparing with staging

fluid theme staging compare reports how this directory's files differ from what the theme's staging branch serves: files whose content changed, files only you have, and files only staging has. It sends each file's SHA-256, never its content, and changes nothing. Publishing to production (fluid theme push) always sends your local files, so compare first when staging may hold work that isn't in this checkout, such as a teammate's staging publish.

Development

For contributors working in this monorepo:

pnpm --filter @fluid-app/fluid-cli-theme-dev build
node packages/cli/core/dist/bin/fluid.mjs theme --help

版本与发布记录

@fluid-app/fluid-cli-theme-dev 共发布 1,227 个版本,首次发布于 2026/03/13;过去 12 个月发布了 1227 个版本。

版本发布日期距今
0.1.1226latest2026/11/17今天
0.1.12252026/11/17今天
0.1.12242026/11/17今天
0.1.12232026/11/17今天
0.1.12222026/11/17今天
0.1.12212026/11/16今天

关于 @fluid-app/fluid-cli-theme-dev 的常见问题

@fluid-app/fluid-cli-theme-dev 是什么?

Fluid CLI plugin for theme developer workflows — dev server, push, pull, init, crawl, compare

如何安装 @fluid-app/fluid-cli-theme-dev?

在项目目录运行 npm install @fluid-app/fluid-cli-theme-dev,或使用 pnpm add / yarn add / bun add。

@fluid-app/fluid-cli-theme-dev 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@fluid-app/fluid-cli-theme-dev 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@fluid-app/fluid-cli-theme-dev 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=24.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@fluid-app/fluid-cli-theme-dev 可以商用吗?

@fluid-app/fluid-cli-theme-dev 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@fluid-app/fluid-cli-theme-dev 的下载量有多少?

根据 npm 官方下载统计,@fluid-app/fluid-cli-theme-dev 在 2026/10/15 – 2026/11/13 这 30 天内被下载 199,548 次,日均约 6,652 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@fluid-app/fluid-cli-theme-dev 还在维护吗?

最新版本 0.1.1226 发布于 2026/11/17(今天);至今共发布 1227 个版本,其中过去 12 个月发布了 1227 个;首次发布于 2026/03/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。