produceTemplate

Note

produceTemplate only generates creations in memory. For the equivalent API to apply those objects, including writing files, see runTemplate.

Given a Template and any settings, creates a Creation output by running the template’s production function(s).

produceTemplate takes in up to two arguments:

1. A template
2. A settings object, only required if the template includes required options. It may contain:
   • options: any options matching the template’s options schema
   • (optional) any other properties from a Template Context

It returns an a Promise for an object with:

• creation: the resultant Creation, including both direct creations and indirect creations
• options: the full merged options that production ran with

For example, given this template that creates a README.md file, produceTemplate would generate an creation object with that file:

import { createTemplate, produceTemplate } from "bingo";
import { z } from "zod";

const template = createTemplate({
  produce() {
    return {
      files: {
        "README.md": `# Hello, World!`,
      },
    };
  },
});

// { creation: { files: { "README.md": "# Hello, World!" } } }
await produceTemplate(template);

Note

produceTemplate() will not run a template’s prepare() method to infer option defaults. Use the prepareOptions API to first generate options that can be passed as settings options.

Settings

options

Any number of options defined by the template’s options schema.

This must include all required options from the schema. It may also include any other optional options.

For example, this Template is run with a title option:

import { createTemplate, produceTemplate } from "bingo";
import { z } from "zod";

const template = createTemplate({
  options: {
    title: z.string(),
  },
  produce({ options }) {
    return {
      files: {
        "README.md": `# ${options.title}`,
      },
    };
  },
});

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

mode

Which mode to run in, as either "setup" or "transition".

If provided, the corresponding setup() or transition() will be called before produce(). Creations from the production methods will be merged per Details > Merging.

For example, this template creates a starter index.js file on setup:

import { createTemplate, produceTemplate } from "bingo";
import { z } from "zod";

const template = createTemplate({
  setup() {
    return {
      files: {
        "index.js": "console.log('Hello, world!');"
      }
    }
  }
  produce({ options }) {
    return {
      files: {
        "README.md": `# My App`,
      },
    };
  },
});

// {
//   creation: {
//     files: {
//       "index.js": "console.log('Hello, world!');",
//       "README.md": "# My App",
//     }
//   },
// }
await produceTemplate(template, { mode: "setup" });

offline

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

This is equivalent to the --offline CLI flag.

For example, this template adds an --offline flag to its installation script if offline is true:

import { createTemplate, produceTemplate } from "bingo";
import { z } from "zod";

const template = createTemplate({
  produce({ offline }) {
    return {
      scripts: [offline ? "pnpm install --offline" : "pnpm install"],
    };
  },
});

// { scripts: ["pnpm install"] }
await produceTemplate(template);

// { scripts: ["pnpm install --offline"] }
await produceTemplate(template, { offline: true });

refinements

Any optional customizations from a template-specific config file.

For example, Stratum templates allow customizing Blocks via refinements:

create-typescript-app.config.ts

import { blockAreTheTypesWrong, template } from "create-typescript-app";
import { produceTemplate } from "bingo";

await produceTemplate(template, {
  refinements: {
    blocks: {
      add: [blockAreTheTypesWrong],
    },
  },
});

See:

• Configuration for general information on configuration files
• Stratum > Details > Configurations for more details on Stratum configuration files