NOTE: This readme file is a mess as it is a work in progress. Please bear with me, I will clean it up and add more information soon. Also, the example blueprints and prefabs listed below are not yet available but will be soon.

What's this

Builda is a simple command-line tool to make building project elements fast and easy.

Builda generates files and folders using something called a 'blueprint', this is a template that contains all the files and directories that you want to create as well as a set of variables (called 'substitutions') that you can use to fill in the template automatically.

You can also build entire projects using super-powered blueprints known as 'prefabs' (see Prefabs below).

Screenshots

Coming soon...

Setup

Installation

You can either install builda as a global module or install it locally into your project, if you choose to install it locally, you will need to run npm run builda or yarn builda instead of just builda.

npm i -g builda

yarn global add builda

npm i --dev builda

yarn add -D builda

Then you can initialise builda by typing builda --init this will create a .builda directory in your project root. (see Configuration below)

Configuration

Note: If you want to use a prefab, you do not need to run builda --init (see Prefabs below)

You can specify some defaults by updating the builda object in your package.json file.

This section is incomplete and will be updated soon

Installing modules

Builda has two different types of modules, 'blueprints' and 'prefabs'.

You can install blueprints by running builda add <blueprint-path>

Installing prefabs is a little different. Instead of installing a prefab, you initialise a project using a prefab.

The command to do that is builda project <prefab-path>

Prefixes

You can put the full path to the module as a url if you wish or you can use a prefixed path (known in Builda as a 'resolver')

e.g. The following command will install the 'arctic-fox' blueprint:

builda add builda:arctic-fox

The builda: prefix tells builda to look at the module registry on the builda trade-store for the appropriate module.

Builda also supports the following prefixes:

github: prefix to install modules from GitHub

e.g. The following command will install the 'arctic-fox' blueprint from the GitHub user 'builda-modules':

builda install github:builda-modules/arctic-fox

bitbucket: prefix to install modules from BitBucket

e.g. The following command will install the 'arctic-fox' blueprint from the BitBucket user 'builda-modules':

builda install bitbucket:builda-modules/arctic-fox

NOTE: github and bitbucket prefixes require a release tag of 'latest' to exist in order to install the module.

Custom prefixes

You can also specify custom prefixes by adding them to the config.json file under resolve:

{
  "resolve": {
    "sn": "https://spacenectar.io/builda/modules"
  }
}

Then you could install 'custom-blueprint' from the spacenectar website by running:

builda add sn:custom-blueprint

Usage

Useful commands

builda init

Initialises builda in your project. This will create a .builda directory in your project root and a config.json file inside that. (see Configuration below)

builda project <prefab-path>

Initialises a new project using a prefab. (see Prefabs below)

builda new <thing>

Creates a new thing from a bluebrint (see Blueprints below)

builda --help

Displays the help menu.

Blueprints

Blueprints can be used to generate files and folders in your project.

Once you have added a blueprint you then need to edit your builda entry in your package.json file to tell builda where to put the output of the blueprint.

Once you have installed a blueprint, you will see a blueprints entry in your builda config. After that entry, you can add a scripts entry which will contain a list of scripts that you can run to generate files and folders.

For example, if you installed the arctic-fox blueprint, you would see the following in your package.json file:

{
  "builda": {
    "blueprints": {
      "arctic-fox": {
        "version": "1.0.0",
        "location": "builda:arctic-fox"
      }
    }
  }
}

You can add a scripts entry below this like so:

{
  "builda": {
    "blueprints": {
      "arctic-fox": {
        "version": "1.0.0",
        "location": "builda:arctic-fox"
      }
    },
    "scripts": {
      "component": {
        "use": "arctic-fox",
        "outputDir": "src/components"
      }
    }
  }
}

This tells builda that any time you want to generate a new component it should use the arctic-fox blueprint and put the output in the src/components directory.

builda new component --name my-example-component

This will generate a component called my-example-component in the src/components directory using the arctic-fox blueprint.

This is a powerful feature as not only does it allow you to specify the directory to generate files in, it also allows you to specify the blueprint to generate from, so you can specify a different blueprint for each type of thing you want to generate.

e.g. You could have a component script which uses the arctic-fox blueprint and a page script which uses the arctic-wolf blueprint.

Prefabs

Blueprints are a great way to build parts of your project, but sometimes you want to build out an entire project. This is where prefabs come in.

A prefab is essentially a massive blueprint, which contains all of the files and directories that you would need to build a project.

A prefab does differ a little from a blueprint in that it is not designed to be modified once it has been created, all prefab files live inside the .builda directory and you use a builda command to run your application and keep your project files in sync.

Why?

The purpose of a prefab is to effectively turn the core parts of your project into a package. This means that you can use the same prefab to build out multiple projects and when you want to update that prefab, a single command inside any project that uses that prefab will pull in the latest changes.

The core of your application is now basically just config. Leaving you free to focus on individual features.

Ok but what if I want parts of the project to be different?

No problem! You can just eject the files you want to update from the prebabs folder into the root of your project. Provided that the paths match up, the files in the root will take precedence over the files in the prefab. This of course means that these files will no longer receive updates when the prefab is updated and you will need to manually update the files in the root if you want them to be updated.

COMING SOON: Prefab migration is on the roadmap. So manually updating the files in the root will eventually be more like a git merge, only requiring manual intervention to resolve conflicts.

Using prefabs

A prefab is an entire project. So rather than installing a prefab as you do with a blueprint. You would initialise builda with the project command and then specify the prefab you want to use.

builda project builda:jackanory

This will build out your new project using the jackanory prefab.

COMING SOON: Prefab partials are on the roadmap. This will allow you to add prefabs to existing projects and have only parts of the project connected to a prefab. This would be useful if you wanted to add a preconfigured package to your project (e.g. storybook) and wanted to keep that preconfiguration in sync with the rest of your projects but still leave the rest of your project as a standalone project.

Migrating from Buildcom

If you previously used the buildcom package then please be aware that although this is the successor to buildcom, it is a completely different package and is not backwards compatible.

If you rely on the legacy buildcom package, you may find that builda covers all of the functionality of buildcom and then some. However as this is an early release, you may find that you are better off staying with buildcom for now.

Roadmap

• Add support for generating multiple components at once

• Add a selection of default blueprints

• Create a website for builda with full documentation

• Add the ability to easily generate your own blueprints

• Create a community marketplace for blueprints and prefabs.

• Add support for migrating to new prefabs without having to manually update custom files.

• Add prefab partials to allow smaller parts of your project to be prefabs but not the whole project.

• Even more stuff!

Get support / discuss builda

I've set up a GitHub Discussions board for builda. Feel free to post questions, bugs, suggestions, or just to chat.

Contribute

Builda is not yet set up to receive contributions, but if you would like to help then please feel free to post questions, suggestions or bug reports on the discussions board (link above). I will be happy to review any pull requests you may have but it makes sense to wait until I release the docs and tools which will make contributing much easier.

Support me

Donate

I made this with love and of course it is free for you to use and modify however you see fit, however if you would like to buy me a coffee to say thanks, I certainly won't complain :)

Patreon

I have a Patreon where you can support me and help me keep this project alive. At the moment I only have a single 'Offer Support' tier but I'm sure I'll be adding more tiers in the future when I get around to fleshing out my page.

How to create a blueprint

Coming soon...

How to create a prefab

At the moment, this is a manual process. I will be adding a tool to make this easier in the future.

Creating the prefab

A prefab requires the following files and directories:

• registry.json - This is the registry file for the prefab. It is used to register the prefab with builda and to specify the name of the prefab.
• README.md - This is the readme file for the prefab. It is used to provide information about the prefab and how to use it.
• A 'modules' directory - This is the directory where all of the files for the prefab are stored.

You can add other files and directories to the prefab if you want, but these will be ignored by builda. If you don't want to install builda globally, you can add a package.json file to the root and install builda as a dev dependency.