About Building Templates

So you’d like to build a repository template with Bingo. Wonderful!

Bingo is still early stage. It runs well but its APIs are still in flux. Please try it out and report any issues on GitHub! 🙏

Getting Started

Bingo templates can be defined in as little as two files:

1. Template File: defining the logic for the template
2. Runner File: script file to run on the CLI

Tip

For example Bingo template repositories, see:

• create-example-minimal: The barest bones template as created by this docs page
• create-example: A larger template with more options and tests

github.com/bingo-examples contains more examples of Bingo templates.

1. Template File

In a new empty directory, create a package.json, install bingo as a dependency, then create a template.js file:

package.json

{
  "name": "my-template",
  "version": "0.0.0",
  "type": "module"
}

npm i bingo

template.js

import { createTemplate } from "bingo";

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

export default template;

export const { createConfig } = template;

You can then provide the path to that file to the bingo CLI to create a README.md file:

npx bingo template.js

README.md

# Hello, world!

🥳 Congratulations! You just built and ran your first template with Bingo.

2. Runner File

Bingo templates provide their own CLI to use instead of bingo.

Create one in an index.js file with the following content:

index.js

#!/usr/bin/env node
import { runTemplateCLI } from "bingo";

import template from "./template.js";

process.exitCode = await runTemplateCLI(template);

Then, add a bin entry for the index.js file to your package.json:

package.json

{
  "name": "my-template",
  "version": "0.0.0",
  "type": "module",
  "bin": "index.js",
  "dependencies": { ... },
}

You and your template’s users will now be able to run your template with npx.

Try it out locally with:

npx .

┌  ✨ my-template@0.0.0 ✨
│
│  Running with mode --transition using the template:
│    my-template
│
◇  Ran my-template
│
└  Done. Enjoy your updated repository! 💝

🥳 Congratulations! You just built and ran your first Bingo template CLI.

Learning More

Here are the main concepts you’ll want to understand:

1. Creations: how the pieces of a repository are described by templates in-memory
2. Modes: the ways Bingo can be run to create a new repository or migrate an existing one
3. Templates: describing how to setup or transition a repository given a set of options

See also API documentation for the functions referenced on this page:

• createTemplate
• runTemplateCLI