How to Use Astryx Page Templates for Common Layout Patterns

Astryx ships ready-to-use page templates located in packages/cli/templates/pages/ that you scaffold via the CLI using npx astryx template <name> to instantly generate complete dashboard, table, form, and login screen layouts.

The facebook/astryx repository provides a comprehensive template system that accelerates UI development by delivering pre-built, accessible page layouts. These templates handle common patterns like searchable data tables and administrative dashboards, allowing you to focus on business logic rather than boilerplate layout code.

Understanding the Template Architecture

The Astryx template system consists of five interconnected components that transform static files into production-ready pages.

CLI Command Handler

The Astryx CLI parses template commands in packages/cli/src/commands/template.mjs. This module discovers available templates by walking the packages/cli/templates/pages/ directory tree, resolves user-selected templates by name, and executes the scaffolding process.

Template Registry

The CLI automatically discovers every template by reading folder names under packages/cli/templates/pages/. Each folder contains a page.tsx file that exports a default React component implementing a complete layout composition using Astryx core primitives.

Page Template Files

Individual templates are pure React components written with Astryx core components like Layout, VStack, Table, and PowerSearch. For example, packages/cli/templates/pages/dashboard/page.tsx provides a complete dashboard implementation with header actions, sidebar navigation patterns, and responsive content areas.

Theme System Integration

Templates assume a global theme is present (typically @astryxdesign/theme-neutral). The CLI does not embed CSS during scaffolding; you must add the theme import globally as documented in the Getting Started guide. This separation allows the same template to render with different design tokens simply by swapping the theme import.

Post-Scaffolding Customization

After the CLI copies a template to your project (e.g., src/app/dashboard/page.tsx), the file becomes standard React code in your repository. You retain full ownership to edit data sources, modify component composition, or integrate with your routing system.

Listing Available Templates

Discover all built-in layout patterns before scaffolding. The CLI reads the packages/cli/templates/pages/ directory and returns human-readable names.

npx astryx template --list

This outputs template identifiers such as dashboard, settings, table-page, and login-card. Each name corresponds to a subdirectory containing the implementation files.

Scaffolding a Page Template

Generate a complete page by specifying the template name and output directory. The CLI copies the source page.tsx, rewrites relative imports to resolve against @astryxdesign/core, and places the file in your target location.

# Scaffold dashboard layout into src/app/dashboard/

npx astryx template dashboard --output src/app/dashboard

The generated file imports Astryx primitives and renders a fully-functional layout immediately:

// src/app/dashboard/page.tsx (generated)
import {
  Layout, LayoutHeader, LayoutContent,
  VStack, HStack, Text, Heading,
  IconButton, Icon, Button,
} from '@astryxdesign/core';
import {PowerSearch} from '@astryxdesign/core/PowerSearch';
import {Table} from '@astryxdesign/core/Table';

export default function DashboardPage() {
  return (
    <Layout>
      <LayoutHeader hasDivider>
        <HStack gap={2} vAlign="center">
          <Heading level={1}>Dashboard</Heading>
          <IconButton label="Settings" icon={<Icon name="settings" />} />
        </HStack>
      </LayoutHeader>
      <LayoutContent>
        <VStack gap={4}>
          <PowerSearch />
          <Table />
        </VStack>
      </LayoutContent>
    </Layout>
  );
}

Connecting Real Data Sources

Scaffolded templates include placeholder data (such as static arrays in table-page). Replace these with dynamic data fetching using standard React patterns while preserving the template's layout structure.

import {useEffect, useState} from 'react';
import TablePageTemplate from '@/templates/table-page/page';
import type {DogRow} from '@/types';

export default function DogTable() {
  const [dogs, setDogs] = useState<DogRow[]>([]);

  useEffect(() => {
    fetch('/api/dogs')
      .then(r => r.json())
      .then(setDogs);
  }, []);

  // Pass fetched data to the template's expected props
  return <TablePageTemplate data={dogs} />;
}

Customizing Layout Components

Since templates export standard React components, you can modify any aspect of the layout. Common customizations include replacing header actions, adjusting stack layouts, or swapping content blocks.

// src/app/dashboard/custom-header.tsx
import {LayoutHeader, HStack, IconButton, Button, Heading} from '@astryxdesign/core';
import {BellIcon, UserIcon} from '@heroicons/react/24/outline';

export default function CustomDashboardHeader() {
  return (
    <LayoutHeader hasDivider>
      <HStack gap={2} vAlign="center">
        <Heading level={1}>My App Dashboard</Heading>
        <IconButton label="Notifications" icon={<BellIcon />} variant="ghost" />
        <IconButton label="Profile" icon={<UserIcon />} variant="ghost" />
        <Button label="Create New" onClick={() => console.log('create')} />
      </HStack>
    </LayoutHeader>
  );
}

Replace the default header in your scaffolded page by importing CustomDashboardHeader and substituting it for the generated LayoutHeader component.

Applying Alternative Themes

Change the visual appearance without modifying template code by switching global theme imports. The templates reference design tokens (colors, spacing, typography) that resolve at runtime based on your global CSS imports.

/* globals.css */
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-y2k/theme.css';

The scaffolded page automatically inherits the new theme's visual properties, including dark mode variants and brand-specific color palettes.

Summary

• Astryx page templates reside in packages/cli/templates/pages/ and provide complete layout implementations for dashboards, tables, forms, and authentication screens.
• Use npx astryx template --list to discover available patterns and npx astryx template <name> --output <path> to scaffold them into your project.
• The CLI copies files from packages/cli/src/commands/template.mjs and rewrites imports to resolve against @astryxdesign/core automatically.
• Templates are pure React components using Layout, VStack, HStack, Table, and PowerSearch primitives that you can customize after scaffolding.
• Connect real data by replacing placeholder arrays with useEffect hooks or data fetching libraries while maintaining the template's layout structure.
• Apply different visual themes by changing global CSS imports; templates automatically adapt to new design tokens without code changes.

Frequently Asked Questions

How do I list all available Astryx page templates?

Run npx astryx template --list in your terminal. The CLI walks the packages/cli/templates/pages/ directory and displays each folder name (such as dashboard, table-page, or login-card) that contains a scaffoldable page.tsx file.

Can I use Astryx page templates without the CLI?

Yes, but you must manually copy files from packages/cli/templates/pages/ into your project and manually resolve import paths. The CLI automates the import rewriting that maps template-relative paths to @astryxdesign/core, so manual setup requires ensuring your module resolution matches the template's import statements.

Where do I add my data fetching logic in a scaffolded template?

Add data fetching logic directly in the generated page.tsx file after scaffolding. Replace the placeholder data arrays (like the static "Dogs" array in table-page) with React state and useEffect hooks, or convert the component to accept props from a parent data loader. The template remains a standard React component that accepts props and renders children.

Do Astryx page templates include styling and themes?

Templates include component structure and layout logic but do not embed CSS. They assume you have imported a global theme (such as @astryxdesign/theme-neutral) in your application's entry point. The components use Astryx design tokens that resolve based on your active theme, allowing the same template to render with different visual styles by changing the CSS import.

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