How to Use the Astryx Template Command to Generate Page Skeletons

The Astryx CLI provides a template sub-command that lets you scaffold a full page (or a reusable block) and, optionally, view a layout skeleton that shows the spatial annotations without writing any files.

The facebook/astryx repository ships with a powerful CLI tool that streamlines the creation of new pages through the Astryx template command. This command acts as a thin wrapper around the core template API, handling everything from collision detection to formatting output. Whether you need to inspect a component hierarchy before coding or generate production-ready files, the template command provides both interactive and programmatic workflows.

Basic Syntax and Available Flags

The entry point for this functionality is located in packages/cli/src/commands/template.mjs. This module defines the CLI interface and parses several key flags that control the scaffolding behavior.

Key flags include:

• --list — Display available templates
• --type — Filter templates by type (e.g., page)
• --skeleton — Preview the layout structure without writing files
• --overwrite (or -f) — Force overwrite existing files
• --json — Output raw data as JSON

Generating a Layout Skeleton with --skeleton

When you want to inspect a template's structure before committing to file generation, use the skeleton mode. In packages/cli/src/commands/template.mjs, the --skeleton flag triggers a special execution path that calls templateApi(name, {...}) with the skeleton option enabled.

The API, implemented in packages/cli/src/api/template.mjs, resolves the template location and builds a markdown-styled skeleton string. This output includes the component hierarchy and annotated layout showing padding, gaps, and nesting.

# Show the layout skeleton for the "dashboard" page template

astryx template dashboard --skeleton

The CLI checks for result.type === 'template.skeleton' and prints a formatted view showing the component tree. By default, this outputs to stdout; add --json to get the raw skeleton data for programmatic processing.

Typical skeleton output looks like this:

# Dashboard — A data-rich overview page

# Components: Header, Sidebar, Chart, Footer

<Header />
<div class="layout">
  <Sidebar />
  <main>
    <Chart />
  </main>
</div>
<Footer />

Scaffolding a Full Page

To generate actual files, provide a target directory as the second argument. The command copies template files from packages/cli/templates/pages/ to your specified location.

# Generate a full page from the "dashboard" template into ./src/pages

astryx template dashboard ./src/pages

This invokes the full template API workflow, which reads the template documentation files (such as template.doc.mjs) and copies the necessary scaffolding into your project.

Collision Detection and Overwrite Protection

Before invoking the API, the CLI runs detectTemplateCollision to check if the target file already exists. This logic, found in packages/cli/src/commands/template.mjs (lines 63-71), mirrors the API's path-safety checks to provide early user feedback.

If a collision is detected and --overwrite is not supplied, the command prompts for confirmation. To bypass this check entirely, use the -f flag:

# Force overwrite without a prompt

astryx template dashboard ./src/pages -f

Understanding the Template API Architecture

The Astryx template command architecture follows a clean separation between CLI concerns and core logic. The command layer in packages/cli/src/commands/template.mjs handles option parsing, collision detection, and output formatting, while the API layer in packages/cli/src/api/template.mjs manages template discovery and content generation.

When skeleton is set to true, the API returns a result object with type 'template.skeleton', containing the layout description. The CLI then formats this for human-readable display or JSON output via jsonOut, depending on the --json flag.

Summary

• The Astryx template command scaffolds pages via packages/cli/src/commands/template.mjs and exposes flags like --skeleton and --overwrite.
• Skeleton mode lets you preview component hierarchies and layout annotations without writing files, using logic from packages/cli/src/api/template.mjs.
• Collision detection (detectTemplateCollision) prevents accidental overwrites unless the -f flag is passed.
• Template definitions reside in packages/cli/templates/pages/ and include documentation files that describe component structure.

Frequently Asked Questions

What is the difference between skeleton mode and full generation?

Skeleton mode (--skeleton) returns a text-based visualization of the component hierarchy and layout structure without modifying the filesystem, while full generation copies actual template files to your target directory. Skeleton mode is useful for planning layouts, whereas full generation creates production-ready scaffolding.

How does Astryx handle file collisions when scaffolding?

Before generating files, the CLI invokes detectTemplateCollision to check if target paths already exist. If collisions are found and the --overwrite (or -f) flag is not provided, the command prompts for confirmation. This safety mechanism is implemented in packages/cli/src/commands/template.mjs to prevent accidental data loss.

Where are template definitions stored in the Astryx repository?

Template definitions are located in packages/cli/templates/pages/ and related directories. Each template typically includes documentation files (such as template.doc.mjs) that describe the component list, layout structure, and usage examples. The API resolves these paths when generating skeletons or scaffolding files.

Can I output the skeleton data as JSON for programmatic use?

Yes. When using the --skeleton flag, add --json to receive the raw skeleton data as JSON instead of formatted text. The CLI uses jsonOut to emit the result object (with type 'template.skeleton') directly to stdout, making it suitable for piping into other tools or scripts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}