runTemplate

Note

runTemplate both generates creations and applies them, including writing files. For the equivalent API to only create those objects in memory, see produceTemplate.

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

runTemplate takes in up to two arguments:

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

It applies those creations, then returns 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, runTemplate would write that file to disk:

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

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

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

Note

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

Settings

directory

Current working directory (“cwd”) path to use for the file system and running scripts. Defaults to ".", or the process cwd.

For example, this produces a template in a child scratch directory:

import { createTemplate, runTemplate } from "bingo";

const template = createTemplate({
  produce({ options }) {
    return {
      files: {
        "README.md": `# My App`,
      },
    };
  },
});

await runTemplate(template, { directory: "scratch " });

scratch/README.md

# My App

The directory will be created if it doesn’t exist.

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, runTemplate } from "bingo";

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 runTemplate(template, { mode: "setup" });

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, runTemplate } 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 runTemplate(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, runTemplate } 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 runTemplate(template, { mode: "setup" });

offline

Whether to skip network requests and generally hint to run in offline mode.

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, runTemplate } from "bingo";
import { z } from "zod";

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

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

// { scripts: ["pnpm install --offline"] }
await runTemplate(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 { runTemplate } from "bingo";

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

See:

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