Producer APIs

Production APIs can be used to create Creations:

• produceBase: generates Base options
• produceBlock: runs a Block production
• produceInput: runs an Input
• producePreset: runs a Preset production

Each production API takes in up to two arguments:

1. The construct to be produced
2. An object with properties from the construct’s context as well as System contexts

Note

Production APIs only generate objects in memory. For APIs that apply those objects, see Runners.

produceBase

Given a Base, creates an options object by running its produce().

produceBase takes in up to two argument:

1. base (required): a Base
2. settings (optional): any properties from a Base Context, except for take

produceBase returns a Promise for the resultant Creation.

For example, given this Base that declares an optional value option that defaults to "default", produceBase can run its produce() with any provided options:

import { createBase, produceBase } from "create";
import { z } from "zod";

const base = createBase({
  options: {
    value: z.string().optional(),
  },
  produce(options) {
    return {
      value: options.value ?? "default",
    };
  },
});

// { value: "default" }
await produceBase(base);

// { value: "override" }
await produceBase(base, {
  options: {
    value: "override",
  },
});

Tip

If the Base does not define a produce(), then settings.options is returned.

offline

Whether to hint to the Base not to make network requests.

This is equivalent to the --offline CLI flag. If provided, Input fetchers will reject with an Error instead of resolving.

For example, this Base is told to run offline:

import { Base } from "create";

declare const base: Base<{}>;

await produceBase(base, {
  offline: true,
});

Caution

offline doesn’t prevent Bases from making network requests outside of the Input fetchers. If you are finding your template still sends requests offline, file a bug on the template.

options

Any number of options defined by the base.

For example, this Base is run with a name option:

import { Base } from "create";
import { z } from "zod";

declare const base: Base<{ name: z.ZodString }>;

await produceBase(base, {
  options: {
    name: "My Production",
  },
});

produceBlock

Given a Block, creates a Creation output by running its produce().

produceBlock takes in up to two arguments:

1. block (required): a Block
2. settings (required): at least options, as well as any other properties from a Block Context

For example, given this Block that produces the start of a README.md file, produceBlock can run its produce() with any provided options:

import { produceBlock } from "create";

import { base } from "./base";

const blockReadme = base.createBlock({
  produce(options) {
    return {
      files: {
        "README.md": `# ${options.title}`,
      },
    };
  },
});

// { files: { "README.md": `# My App` }}
await produceBlock(blockReadme, { options: { title: "My App" } });

args

Any number of Args defined by the Block.

For example, given this Block with a prefix Arg and a name Option, both can be specified in produceBlock:

import { Block } from "create";

declare const block: Block<{ prefix: string }, { name: string }>;

await produceBlock(block, {
  args: {
    prefix: "The",
  },
  options: {
    name: "Production",
  },
});

created

Any Creations to simulate having been made from previously-produced Blocks.

offline

Whether to hint to the Block not to make network requests.

This is equivalent to the --offline CLI flag. If provided, Input fetchers will reject with an Error instead of resolving.

For example, this Base is told to run offline:

import { produceBlock } from "create";

import { base } from "./base";

declare const block: Block<{}, {}>;

await produceBlock(block, {
  offline: {},
  options: {},
});

options

Any number of options defined by the Block’s Base.

For example, this Block is run with no Args and one name Option:

import { Block } from "create";

declare const block: Block<never, { name: string }>;

await produceBlock(block, {
  options: {
    name: "My Production",
  },
});

produceInput

Given an Input, runs its produce() with any provided args.

produceInput takes in up to two arguments:

1. input (required): an Input
2. settings (required): at least options, as well as any other properties from an Input Context other than take

produceInput returns a Promise for the result of the Input’s produce().

For example, this Input production reads data from an existing data.json file on disk:

import { createInput, produceInput } from "create";

const inputDataJson = createInput({
  async produce({ fs }) {
    return await JSON.parse(await fs.readFile("data.json"));
  },
});

// Type: string
await produceInput(inputDataJson);

args

For example, this Input production reads data from a JSON file on disk by path:

import { createInput } from "create";
import { z } from "zod";

const inputJsonFile = createInput({
  args: {
    path: z.string(),
  },
  async produce({ args, fs }) {
    return await JSON.parse(await fs.readFile(args.path));
  },
});

await produceInput(inputJsonFile, {
  args: "data.json",
});

producePreset

Given a Preset, creates a Creation output by running each of its Blocks produce().

producePreset takes in up to two arguments:

1. preset (required): a Preset
2. settings (required):
   • addons (optional): any additional Addons to provide to Blocks
   • blocks (optional): any additions and/or removals of Blocks
   • options (required): Base options to run with
   • (optional) any other properties from a Block Context

producePreset returns a Promise for an object containing:

• creation: The Preset’s Creation, including both direct creations and indirect creations
• options: The full merged options that production ran with

For example, given this Preset that includes the block from produceBlock, producePreset can run its produce() with any provided options:

import { producePreset } from "create";

import { base } from "./base";
import { blockReadme } from "./blockReadme";

const preset = base.createPreset({
  blocks: [blockReadme],
});

// { creation: { files: { "README.md": `# My App` }}, options: { title: "My App" } }
await producePreset(preset, { options: { title: "My App" } });

addons

Any additional Addons to provide to Blocks.

For example, this production adds a "generated" Addon to a Prettier Block:

import { Preset, producePreset } from "create";
import { z } from "zod";

import { blockPrettier } from "./blockPrettier";

declare const preset: Preset<{ name: z.ZodString }>;

await producePreset(preset, {
  addons: [blockPrettier({ ignores: ["generated"] })],
  options: {
    name: "My Production",
  },
});

See Configuration > addons for how this is used.

blocks

Any Blocks to add and/or remove.

For example, this production swaps in a Jest Block instead of a Vitest Block:

import { Preset, producePreset } from "create";
import { z } from "zod";

import { blockJest } from "./blockJest";
import { blockVitest } from "./blockVitest";

declare const preset: Preset<{ name: z.ZodString }>;

await producePreset(preset, {
  blocks: {
    add: [blockJest],
    exclude: [blockVitest],
  },
  options: {
    name: "My Production",
  },
});

See Configuration > blocks for how this is used.

offline

Whether to hint to the Preset not to make network requests.

This is equivalent to the --offline CLI flag. If provided, Input fetchers will reject with an Error instead of resolving.

For example, this Preset is told to run offline:

import { Base } from "create";
import { z } from "zod";

declare const preset: Preset<{}>;

await producePreset(preset, {
  offline: true,
  options: {},
});

Caution

offline doesn’t prevent Presets from making network requests outside of the Input fetchers. If you are finding your template still sends requests offline, file a bug on the template.

options

Any options defined by the Preset’s Base.

This must include all required Options from the Base. It may also include any other optional Options.

For example, this Preset is run with a name option:

import { Preset, producePreset } from "create";
import { z } from "zod";

declare const preset: Preset<{ name: z.ZodString }>;

await producePreset(preset, {
  options: {
    name: "My Production",
  },
});

System Overrides

The properties specific to System Contexts can be overridden in production APIs.

This can be useful if you’d like a production’s Inputs to run in a virtual environment or otherwise augment system interactions.

For example, this Block production adds an authorization header to all network requests:

import { produceBlock } from "create";
import { Octokit } from "octokit";

import { blockUsingNetwork } from "./blockUsingNetwork";

const fetch = async (...args) => {
  const request = new Request(...args);
  request.headers.set("Authorization", "Bearer ...");
  return await fetch(request);
};

await produceBlock(blockUsingNetwork, {
  fetchers: {
    fetch,
    octokit: new Octokit({ request: fetch }),
  },
});

Tip

For testing productions in fully isolated environments, see Testers.