CLI

loom — Roblox UI preview

Usage:
  loom preview [dir] [--port <n>] [--host] [--targets [glob]]
  loom build   [dir] --targets [glob] [--out <dir>] [--base <path>] [--no-assets]

Any other first argument (including none) prints this usage text and exits 0.

loom preview

Starts a Vite dev server with loomPreview() pre-applied and configFile: false, so the project’s own vite.config.ts is ignored.

Mode selection

The CLI picks gallery or single-entry mode and hands the result to loomPreview() as targets. The plugin serves either way, so loomPreview({ targets }) in your own config behaves identically.

1. --targets present, or loom.config.ts supplies targets → gallery mode. The generated page mounts targets itself. No client entry is needed, and a project’s own index.html is overridden.

2. Otherwise, a project index.html is used as-is.

3. Otherwise a page is generated with a full-viewport #loom-root and a module script pointing at the first matching entry:

   src/main.client.tsx
   src/main.client.ts
   src/client/main.client.tsx
   src/client/main.client.ts
   src/main.tsx
   src/main.ts
   src/index.tsx
   src/client.tsx

4. If none exist → exit 1 listing the candidates. The CLI pre-flights the same lookup the plugin would do, so this is a clean exit rather than a server that fails on first request.

File-system access

server.fs.allow is the union of the project directory, the nearest ancestor containing a pnpm-workspace.yaml, and the directory holding the installed @loom-dev/preview sources. .git alone is not a workspace marker — it would over-widen access to a home-directory repository.

loom build

Runs vite build programmatically over the same gallery and writes a self-contained, client-only SPA. It is loomPreview({ targets }) under vite build with configFile: false, so a project whose own config passes targets emits the same output.

build does not read loom.config.ts, and exits non-zero with no targets matched … — nothing to build when the glob matches nothing.

On success it prints the resolved output directory:

  loom build → /Users/you/code/my-ui/dist-preview

loom.config.ts

Read only by preview, from <dir>/loom.config.ts. It is imported through tsx, and an import failure prints a warning and is otherwise ignored.

export default {
  targets: "src/scenes",   // string | string[]
  port: 5204,              // number
};

Precedence and validation:

• CLI flags always win over the file.
• targets must be a string or a non-empty array of strings.
• port is honoured only when targets is valid. A config with a missing or malformed targets is skipped in full, port included, with a hint on stderr.

Glob semantics

--targets normalization:

Leading ./ and trailing slashes are stripped first. The matcher supports three constructs: **/ for any depth including none, ** for anything, and * for anything but /. Every other character is literal.

Discovery walks the project recursively, skipping node_modules and dot-entries, and returns sorted POSIX-style relative paths. Unreadable directories are skipped rather than fatal.

Live target discovery

Under the dev server, adding or deleting a *.loom.tsx file invalidates the virtual target module and triggers a full page reload, since the sidebar is rebuilt from the import map. The URL hash survives it, and editing a target’s contents is ordinary HMR.

loom-dev/embed — the programmatic API

Both commands own the process: preview binds a port, build owns an output directory. A host application owns both already, so loom-dev/embed exposes the same two pipelines as functions:

import { createGalleryServer, buildGallery } from "loom-dev/embed";

const gallery = await createGalleryServer({
  root: "/path/to/my-ui",       // project the targets live in
  targets: "src/scenes",        // same semantics as --targets
  base: "/loom-preview/",       // public path it answers under
});

hostServer.middlewares.use(gallery.middleware);
// …and on shutdown:
await gallery.close();

await buildGallery({
  root: "/path/to/my-ui",
  targets: "src/scenes",
  outDir: "dist/loom-preview",  // --out
  // base defaults to "./" — relative assets, hostable anywhere
});

createGalleryServer also takes hmrPort. Middleware mode has no HTTP server of its own to upgrade, so Vite always puts HMR on a standalone port. Its default, 24678, is the first port every other Vite dev server grabs. A collision is quiet rather than fatal: Vite logs it, and previews never hot-reload. Left unset, loom picks a free port per server.

middleware answers only under base, redirecting the bare /loom-preview to the trailing-slash form. It calls next() for everything else, so it is safe ahead of the host’s own routes. Everything else matches the CLI: the same target discovery, the same URL contract, the same per-target error containment.