Stratum Producer APIs

Stratum generally reuses existing Bingo producer APIs when possible:

• Base options can be prepared using the same API as Templates: prepareOptions > Custom Engine Preparations.
• Templates are standard Bingo templates, and so can be provided to produceTemplate and runTemplate.

The bingo-stratum package provides additional producer APIs for other layers:

• produceBlock: runs a Block production
• producePreset: runs a Preset production

Each Stratum production API allows up to two parameters:

1. The construct to be produced
2. An object with properties from the corresponding Stratum Context

Note

Stratum production APIs only generate creations in memory. For APIs to apply those creations, see Runners.

produceBlock

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

produceBlock allows up to two parameters:

1. block (required): a Block
2. context (optional): any 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 { Base, createBlock } from "bingo-stratum";

declare const base: Base<{ title: string }>;

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

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

addons

Any number of Addons defined by the Block.

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

import { Base, createBlock } from "bingo-stratum";

declare const base: Base<{ name: string }>;

const blockPrefixedReadme = base.createBlock({
  addons: {
    prefix: z.string().default("My"),
  },
  produce({ addons, options }) {
    return {
      files: {
        "README.md": `# ${addons.prefix} ${options.title}`,
      },
    };
  },
});

// { files: { "README.md": `# The App` }}
produceBlock(blockPrefixedReadme, {
  addons: {
    prefix: "The",
  },
  options: {
    name: "App",
  },
});

offline

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

This is equivalent to the --offline CLI flag. If provided, Input Context fetchers will be hinted not to make any network requests.

For example, this Base is told to run offline:

import { produceBlock } from "bingo";

import { base } from "./base";

const blockInstallDependencies = base.createBlock({
  produce({ offline }) {
    return {
      scripts: [offline ? "pnpm install --offline" : "pnpm install"],
    };
  },
});

// { scripts: ["pnpm install"] }
produceBlock(blockInstallDependencies);

// { scripts: ["pnpm install --offline"] }
produceBlock(blockInstallDependencies, { offline: true });

options

Any number of options defined by the Block’s Base, as well as preset: string.

For example, this Block is run with one repository option:

import { createBase } from "bingo-stratum";
import { z } from "zod";

const base = createBase({
  options: {
    repository: z.string(),
  },
});

const blockPackageJson = createBlock({
  produce() {
    return {
      files: {
        "package.json": JSON.stringify({ name: options.repository }),
      },
    };
  },
});

// { files: { "package.json": `{repository":"my-app"}` } }
produceBlock(block, {
  options: {
    preset: "test",
    repository: "my-app",
  },
});

producePreset

Given a Preset and the name of one of its Presets, creates a Creation output by running each of its Blocks produce().

producePreset allows up to two parameters:

1. preset (required): a Preset
2. settings (optional): any of the following properties

producePreset returns the Preset’s Creation, including both direct creations and indirect creations.

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

import { producePreset } from "bingo";

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

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

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

offline

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

This is equivalent to the --offline CLI flag. If provided, Input Context fetchers will be hinted not to make any network requests.

For example, this Template is told to run offline:

import { Template from "bingo";
import { z } from "zod";

declare const preset: Preset;

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

Caution

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

options

Any options defined by the Preset’s Base, as well as preset: string.

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

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

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

Adding Base Options

Although Presets are associated with Bases, running producePreset does not automatically infer default option values. If you want to include the inferred options from a Preset’s Base you’ll have to call the prepareOptions API first yourself.

For example, this directly passes produced Options from a Base to a Preset:

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

const options = await prepareBase(base);

producePreset(preset, { options });

refinements

Any optional Stratum customizations. These are analogous to Details > Configurations > Refinements.

addons

Any Addons to pass to the Preset’s Blocks.

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

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

import { blockPrettier } from "./blockPrettier";

declare const preset: Preset;

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

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

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

declare const preset: Preset;

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

See Configurations > blocks for how this is used.

template

Parent Template that contains the Preset. This is used to resolve any Block Refinements that add blocks.

For example, this production runs a Preset that includes an “Extra Fun” Block from its parent Template:

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

declare const preset: Preset;
declare const template: Template;

producePreset(preset, {
  options: {
    "add-extra-fun": true,
    name: "My Production",
  },
  preset: "example",
});