builda
v5.2.4
Published
The everything generator
Downloads
31
Maintainers
Readme
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.