Introduction
Go is a new tool for creating and using boilerplates designed to be simple to start, and fast to get it done. Go is delivered with a minimal toolset to let you immediately create boilerplates and it can be easily extended with plugins.
Table of Contents
Quick Start
For those who would like to try it immediately, install Go and try our boilerplate:
$ npm install --global go $ go git git@github.com:gocli/boilerplate-example.git
You will be asked a few questions and once you answered them the folder boilerplate-example
will be created.
What is Boilerplate?
The boilerplate is just a bunch of files hosted somewhere, for example as GitHub repository. So if you already have the repository you can install it using Go. Here is an example:
$ go git git@github.com:<username>/<repository>.git <destination/path>
Go supports many more options to install boilerplates! You may use any git hostings, different boilerplate sources or even create your own loader.
Creating Boilerplates
Creating boilerplates is as easy as putting needed files in a right place in one folder. After you will host your boilerplate somewhere you and others will be able to install them via Go. In addition to that you can you can put Go meta files to your boilerplate to configure it and add some API.
.goconfig.json
If you need to run a script after your boilerplate is loaded add .goconfig.json
file to your boilerplate.
It should contain key install with a string as a value that will be executed in a shell.
Run Make command:
{ "install": "make" }
Execute JavaScript file:
{ "install": "node scripts/install.js" }
Install node dependencies and run Go command:
{ "install": "npm install && go install" }
gofile.js
gofile.js
is an engine of your boilerplate.
Using this file you are able to create an API for your boilerplate in a fast way thanks to plugins.
Here is an example of using it:
const go = require('go') go.registerCommand('install', async () => { const name = go.ask('Let\'s name your project first:') const yarn = go.confirm('Do you want to use Yarn instead of NPM?') go.processTemplates({ name, yarn }) })
Go Plugins
Go plugin is basically just a function that extends Go prototype object. There is a list of plugins that are pre-installed with GO:
- Go FS ‐ working with file system
- Go CLI ‐ creating CLI API
- Go Templates ‐ processing your templates
- Go Quiz ‐ collecting an input from user
If you want to create your own plugin, you can see how to do it Creating Plugins chapter. You can also find ready to use plugins in our directory.
To use a plugin you should install it:
const go = require('go') const MyPlugin = require('my-go-plugin') go.use(MyPlugin)
What is Loader?
Go let's you to host your boilerplates everywhere you want. It uses loaders to install them from any source. If a loader for your preferred source is missing you can create your own loader.
Here are loaders that are pre-installed with Go:
Git Loader
With Git Loader you can use git repositories as a source of your boilerplate. You can use both https and ssh links to load them:
$ go git https://gitlab.com/repo/name.git $ go git git@gitlab.com:repo/name.git
Go to Git Loader page to read more about it.
More loaders can be viewed in links section.
Contributing
Go is higly extensible for yout needs!
Creating Plugins
Go plugin is a function or an object with a function stored under install key. The function will be called with Go prototype object and options given when registering plugin.
const go = require('go') const LoggerPlugin = proto => { const time = () => (new Date).toString().split(' ')[4] proto.log = (...args) => console.log(time(), ...args) } go.use(LoggerPlugin)
Example, with options object:
const go = require('go') const AdvancedLoggerPlugin = (proto, options = {}) => { const time = () => { const date = (new Date).toString().split(' ') if (options.withDate) { return date.slice(1, 5).join(' ') } return date[4] } proto.log = (...args) => console.log(time(), ...args) } go.use(AdvancedLoggerPlugin, { withDate: true })
Creating Loaders
Loaders are NPM packages named as go-loader-NAME
.
The NAME
will be used to trigger the loader.
The package should export an object with execute key containing a function.
This function will be called with args given when loader is executed.
Here is an example of a loader that installs boilerplates from Zip archives:
package.json
{ "name": "go-laoder-zip", "main": "loader.js", "dependencies": { "decompress": "*", "decompress-unzip": "*" } }
loader.js
const decompress = require('decompress') const decompressUnzip = require('decompress-unzip') const ZipLoader = async ({ args }) => { const [ loader, source, destination ] = args if (!source || !source.toLowerCase().endsWith('.zip')) { throw new Error('path to zip is required') } return decompress( source, destination || source.slice(0, -4), { plugins: [decompressUnzip()] } ) } exports.execute = ZipLoader
This loader can be installed as a global or local package. And then it can be called in a such way:
$ go zip ./boilerplates/extension.zip ./new-extension
Do not name your plugins after GoLang commands! This will cause troubles for developers who will install your loader and is using Go programming language.
Links
If you willing to see more, visit our awesome-go page.
Plugins
- Cli Plugin - register and execute commands.
- FS Plugin - simplify the work with files and folders.
- Quiz Plugin - collect user input.
- Templates Plugin - process templates using Embedded JavaScript templates.
Loaders
- Git Loader - installs boilerplates from GitHub, Bitbucket, GitLab or any other git repository available via SSH or HTTP.
Templates
- gocli/boilerplate-example - boilerplate that uses all features that are delivered with pure Go installation.