Write the template file

Astryx copies just this one file into an app, so write it to work on its own there: where it lands, what it can import, and what it exports.

Know what gets copied

astryx template copies exactly one source file. It does not copy sibling helpers, stylesheets, fonts, icons, images, or media. Plan for that before you add supporting files.

Template	Directory target	Explicit file target
Page	Writes `<target>/page.tsx`	Writes the exact file path
Block	Writes `<target>/<source-basename>.tsx`	Writes the exact file path

bash
# Page: src/app/account/page.tsx
npx astryx template acme-account src/app/account
# Block: src/features/account/acme-stat-card.tsx
npx astryx template acme-stat-card src/features/account
# Exact destination for either kind
npx astryx template acme-stat-card src/features/account/StatusCard.tsx

Astryx refuses to replace an existing file unless the caller passes --overwrite or -f.

Keep edited code in one file

Put every helper that the app is expected to edit in the template source. Small local components, example data, constants, and event handlers can live above or below the default component in the same file.

Inline a helper when it is part of the editable starting point.
Move a helper into the integration package only when it should stay package-owned and update with the package.
Do not import ./helper, ./styles, or any other sibling file.
Do not create routes, configuration, or extra files at runtime. Give the app one explicit source file to own.

Use imports that work in the app

After the copy, imports resolve from the app, not from the template directory. Every bare import must name a package the app installs, and every package path must be public.

tsx
import {Button} from '@astryxdesign/core/Button';
import {Card} from '@astryxdesign/core/Card';
import {HStack, VStack} from '@astryxdesign/core/Stack';
import {Text} from '@astryxdesign/core/Text';
import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';
const metrics = [
  {label: 'Healthy accounts', value: '1,248'},
  {label: 'Needs review', value: '37'},
];
function MetricRow({label, value}: {label: string; value: string}) {
  return (
    <HStack justify="between">
      <Text>{label}</Text>
      <Text>{value}</Text>
    </HStack>
  );
}
export default function AcmeAccountSummary() {
  return (
    <Card>
      <VStack gap={4}>
        <AcmeStatusCard />
        {metrics.map(metric => <MetricRow key={metric.label} {...metric} />)}
        <Button label="Review accounts" />
      </VStack>
    </Card>
  );
}

Import Astryx components from their public Core paths.
Import integration-owned components, helpers, icons, or styles only through paths the package exports (astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/export-template-assets).
Avoid adding another library when Astryx or platform APIs already provide the behavior.

Export one component

The source must default-export one React component. Named helpers inside the file are fine.

Add use client as the first statement only when hooks, event handlers, or browser APIs need a client boundary.
Keep a static template server-compatible when it needs no client behavior.