Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
8.1 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file FunctionDoc for `template()` / `astryx template`. Colocated with the API
 * function it documents; the shape source of truth stays in `template.type.mjs`.
 * @position packages/cli/api/template — function documentation
 */

/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
export const doc = {
  type: 'function',
  kind: 'api',
  name: 'template',
  namespace: 'cli/api',
  displayName: 'template()',
  summary: 'List, inspect, or scaffold page and block templates.',
  description:
    'One entry point for the template family: with no name it lists the discovered ' +
    "templates; with a name it returns that template's source, a layout skeleton, or " +
    'scaffolds it into the project. A configured integration may replace a Core ' +
    'template id for unqualified discovery and lookup; package selection still ' +
    'addresses the Core original. Other duplicate ids remain ambiguous and can be ' +
    'narrowed by type and/or package. The cdn option writes the annotated ' +
    'no-build-step CDN starter page, which ships as an asset rather than as ' +
    'a discovered template.',
  importPath: '@astryxdesign/cli/api',
  signature:
    'template(name?: string, options?: TemplateOptions): Promise<TemplateListResponse | TemplateShowResponse | TemplateSkeletonResponse | TemplateCopyResponse | TemplateCdnResponse>',
  keywords: [
    'template',
    'scaffold',
    'page',
    'block',
    'skeleton',
    'starter',
    'cdn',
    'esm',
    'importmap',
    'no-build',
  ],
  params: [
    {
      name: 'name',
      type: 'string',
      description:
        'Template id to resolve. Omit to list every discovered template.',
    },
    {
      name: 'options.list',
      type: 'boolean',
      description:
        'List templates instead of scaffolding; refused with ERR_INVALID_ARGUMENT when a name or path is also given.',
      default: 'false',
    },
    {
      name: 'options.skeleton',
      type: 'boolean',
      description:
        'Return a compact layout skeleton (structural tags with spatial annotations) instead of the full source.',
      default: 'false',
    },
    {
      name: 'options.cdn',
      type: 'boolean | string',
      description:
        'Write the annotated no-build-step CDN starter page instead of resolving a template. Answers before discovery, so no name is involved; pass a string to use it as the destination path.',
      default: 'false',
    },
    {
      name: 'options.show',
      type: 'boolean',
      description:
        'Return the template source. This is the default for a named lookup with no target path.',
      default: 'false',
    },
    {
      name: 'options.type',
      type: "'page' | 'block'",
      description:
        'Filter list views, or narrow an ambiguous name, to a single template kind.',
    },
    {
      name: 'options.package',
      type: 'string',
      description:
        'Narrow lookups to templates from a specific owning package. Without it, a valid integration replacement is selected for the Core id; use @astryxdesign/core to select the original.',
    },
    {
      name: 'options.targetPath',
      type: 'string',
      description:
        'Destination (relative to cwd) to scaffold the template into. Its presence switches a named lookup into a copy. ' +
        "A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; any other path is a directory, which receives page.tsx for a page template or the block's own file name for a block.",
    },
    {
      name: 'options.overwrite',
      type: 'boolean',
      description: 'Overwrite an existing target file instead of erroring.',
      default: 'false',
    },
    {
      name: 'options.cwd',
      type: 'string',
      description:
        'Directory to discover templates and resolve the target path from.',
      default: 'process.cwd()',
    },
  ],
  returns: [
    {
      type: 'template.list',
      description:
        'The effective templates (page + block); a valid integration replacement takes the place of its Core target and carries `replaces`. Pass `package` to list one package, including replaced Core originals.',
    },
    {
      type: 'template.show',
      description:
        "The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and `demoMediaReplaced` — how many Astryx demo media references (images, posters, videos) in the source were replaced with placeholders for you to swap for your own media, and `demoContentReplaced` — how many Astryx docs-only demo content elements were replaced with a `<Text>` placeholder for your own content.",
    },
    {
      type: 'template.skeleton',
      description:
        "A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.",
    },
    {
      type: 'template.copy',
      description:
        'A receipt after scaffolding the template into the project: the template id, output directory, written file name, file count, `demoMediaReplaced` — how many Astryx demo media references were replaced with placeholders, `demoContentReplaced` — how many Astryx docs-only demo content elements were replaced with a `<Text>` placeholder, `notes` — setup notes naming what the template needs that the project lacks (missing packages, missing StyleX compiler; empty when satisfied), `missingPackages` — external package names the template imports that are not in the project, and `installCommand` — a ready-to-run install command with the detected package manager and workspace version ranges (null when nothing is missing, or when several lockfiles leave the package manager undetermined; `missingPackages` still names the packages).',
    },
    {
      type: 'template.cdn',
      description:
        'A write receipt for the CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.',
    },
  ],
  throws: [
    {
      code: 'ERR_INVALID_ARGUMENT',
      when: '--cdn is combined with <name>, --list, --skeleton, --type, or --package; --list is combined with <name>, <path>, --skeleton, or --overwrite; --skeleton is combined with <path> or --overwrite; or options.list is set with a type outside page or block, or with a package that provides no templates (a valid filter that matches nothing returns an empty list instead)',
    },
    {
      code: 'ERR_UNKNOWN_TEMPLATE',
      when: 'the named template does not exist, or options.skeleton is set without a name',
    },
    {
      code: 'ERR_AMBIGUOUS_TEMPLATE',
      when: 'the name matches more than one template across kinds/packages; narrow it with type and/or package',
    },
    {
      code: 'ERR_NO_SOURCE',
      when: 'the resolved template has no source file on disk',
    },
    {
      code: 'ERR_PATH_TRAVERSAL',
      when: 'the copy target path is absolute or escapes the project root',
    },
    {
      code: 'ERR_FILE_EXISTS',
      when: 'the copy target already exists and overwrite is not set',
    },
    {
      code: 'ERR_WRITE_FAILED',
      when: 'the copy target could not be written (no permission, read-only mount, full disk); nothing is written',
    },
  ],
  examples: [
    {label: 'List templates', code: 'const {data} = await template();'},
    {
      label: 'List exact Core ids',
      code: "await template(undefined, {list: true, package: '@astryxdesign/core'});",
    },
    {label: 'Show source', code: "await template('dashboard');"},
    {
      label: 'Select a replaced Core original',
      code: "await template('shell-side-nav', {package: '@astryxdesign/core'});",
    },
    {
      label: 'Layout skeleton',
      code: "await template('dashboard', {skeleton: true});",
    },
    {
      label: 'Scaffold into the project',
      code: "await template('dashboard', {targetPath: './app/page.tsx'});",
    },
    {
      label: 'CDN starter page',
      code: 'await template(undefined, {cdn: true});',
    },
  ],
  command: 'template',
  related: ['component', 'search', 'discover', 'init'],
};