Bingo | Blog

Bingo is Early Adopter Ready

Mon, 14 Apr 2025 00:00:00 GMT

Hello, world! 💝

Bingo is a new repository template framework. It allows you to build delightful templates for web repositories with built-in support for friendly CLIs, type-safe options, and fully testable templates.

After half a year of early development, I’m happy to announce that Bingo is “early adopter ready”.

What’s Bingo, you ask? What does early adoption mean? Great questions - read on to learn more!

Why a Template Framework?

Building web templates like create-typescript-app are surprisingly difficult to create and maintain. Templates need to do more than just copy and paste static files into a new Git repository. Popular templates generally at least:

Provide configurable options such as what framework(s) or language to include
Prompt for details such as repository name from the running user
Substitute in those details into the appropriate files based on selected options

Plus, many teams need to configure more than just the files in their repositories. GitHub repository settings such as branch rulesets and labels are often must-haves for many teams. Those can be painstaking to configure manually, especially for settings such as required status checks that can be different depending on the script(s) used in a repository.

Bingo?

Bingo is a framework for delightful web repository templates. It provides rich scaffolding for flexible repository templates that describe the files and settings for projects.

You can think of Bingo as a framework the same way that Express.js or React are frameworks. Instead of giving it a description of a UI (à la React) or an HTTP server (à la Express), Bingo takes in a description of how to create the files to scaffold a repository.

Templates built with Bingo can do as little as define a small set of files and as much as describe the API calls and shell scripts that must be run with initializing a new repository and/or migrating it to a newer version of its Bingo template.

A straightforward Bingo template will generally at least define: an option schema describing what configurable options they take in, along with a produce() function to turn those options into files. Files are represented as in-memory strings.

This template defines owner and repository options that are turned into package.json and README.md files:

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

export default createTemplate({
  options: {
    owner: z.string(),
    repository: z.string(),
  },
  produce({ options }) {
    return {
      "package.json": JSON.stringify({
        name: options.name,
        repository: `github:${options.owner}/${options.repository}`,
      }),
      "README.md": `# ${options.repository}\n\nHello, world!`,
    };
  },
});

That’s all you have to do define your first Bingo template! ✨

Bingo templates can onboard many more features, including:

Early Adopter Ready?

Bingo is ready for you to use.

The 2.x version of create-typescript-app (“CTA”) has used Bingo in production for several months. CTA’s 2.x graduated from beta to stable last month. It was able to do so because Bingo is generally stable at runtime: it does not crash in common usage scenarios and its APIs are documented.

However, keep in mind that Bingo is still early stage and pre-1.x. It hasn’t been used by any other projects beyond CTA. Some APIs will likely change over the next year as early adopters put Bingo through its paces. There will likely be many bugs, documentation issues, and important features to be resolved before Bingo stabilizes.

The benefit of being an early adopter is that you’ll get hands-on support from me, the creator, as you try Bingo out. Bugs and missing features you discover will be prioritized early on so you can have as great a repository template as possible built on Bingo.

Getting Started

The Bingo framework is a huge step forward in how to define repository frameworks. I hope you’ll join me in trying it out. Your First Bingo Template will walk you through building your first template with Bingo.

Please, try Bingo out and give feedback:

Bingo’s Discord: Join if you’d like to chat about Bingo and/or get help with templates
github.com/bingo-js/bingo is always open for bug reports, documentation suggestions, and feature requests

Thanks for reading, and I look forward to seeing what you build with Bingo! 💝

Your First Bingo Template

Thu, 20 Feb 2025 00:00:00 GMT

Bingo is a framework for delightful web repository templates. This guide will walk you through creating your first template with Bingo. You’ll see how to define a template that creates a single file, run that template locally with a Bingo CLI, and give that template its own CLI.

Requirements

Bingo requires Node.js LTS. As long as you can run npm install or an equivalent, you can develop with Bingo.

Getting Started

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

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

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 in a generated/ directory:

npx bingo template.js --directory generated

┌  ✨ bingo@... ✨
│
◇  Imported ./template.js
│
◇  Running with mode --setup
│
◇  Inferred default options from system
│
▲  Running in local-only mode. Add string-like options.owner and options.repository schemas to enable creating a repository on GitHub.
│
◇  Ran the bingo template.js template
│
◇  Prepared local Git repository
│
│  You've got a new repository ready to use in:
│    ./generated
│
└  Thanks for using bingo! 💝

generated/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. That way end-users don’t need to install any Bingo dependencies, just the template.

Create 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 . --directory generated

┌  ✨ my-template@0.0.0 ✨
│
◇  Running with mode --transition
│
◇  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:

Creations: how the pieces of a repository are described by templates in-memory
Modes: the ways Bingo can be run to create a new repository or migrate an existing one
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: