# How to Use the Astryx Template Command to Generate Page Skeletons

> Learn to use the Astryx template command to effortlessly generate page skeletons and view spatial annotations without writing files. Streamline your development workflow today.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-07-02

---

**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.

```bash

# 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.

```bash

# 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:

```bash

# 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.