@ajhenry/stack

A CLI to bootstrap dev environments lightning fast ⚡

Features • How To Use • Why • Documentation • Examples • License

Features

Create simple scripts that allow developers to setup projects with minimal effort and without having to refer to the documentation multiple times.

• Simplicity & Usability - These are the two most important aspects that stack follows to provide developers a better project bootstrap experience
• Cross Platform Support - The issue with bash scripts is that they might work on all the common architectures. stack provides the promise that it works everywhere
• Minimal Time to Contribute - The less time that a developer has to spend setting up a dev environment, the more they can spend on actually contributing

⚠️ This project is still very much a work in progress, expect things to break and change often until 1.0 ⚠️

What it is

Clone, download dependencies, setup environments, and more all in basically one command.

Define bootstrap steps for your project to make setup as simple as possible.

Usage

Install

via npm

npm i -g @ajhenry/stack

Example

$ npm install -g @ajhenry/stack
$ stack COMMAND
running command...
$ stack (-v|--version|version)
@ajhenry/stack/0.2.0 win32-x64 node-v14.14.0
$ stack --help [COMMAND]
USAGE
  $ stack COMMAND
...

Commands

• stack file [FILE] [DIRECTORY]
• stack help [COMMAND]
• stack repo PROJECT [DIRECTORY]

stack file [FILE] [DIRECTORY]

Bootstrap a project via a local .stack file and start the dev environment

USAGE
  $ stack file [FILE] [DIRECTORY]

ARGUMENTS
  FILE       File path to read from
  DIRECTORY  Directory to install to

OPTIONS
  -d, --debug      Enable debug mode
  -h, --help       show CLI help
  -o, --overwrite  Overwrite the specified directory

See code: src\commands\file.ts

stack help [COMMAND]

display help for stack

USAGE
  $ stack help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

stack repo PROJECT [DIRECTORY]

Bootstrap a project via a local .stack file and start the dev environment

USAGE
  $ stack repo PROJECT [DIRECTORY]

ARGUMENTS
  PROJECT    GitHub project (org/repo) to read the stack file from
  DIRECTORY  Directory to install to, default is the project's repo name

OPTIONS
  -b, --branch=branch  Branch to use when looking for stack file, default is repo's default
  -c, --common=common  Select a common utility to use to start the project
  -d, --debug          Enable debug mode
  -h, --help           show CLI help
  -o, --overwrite      Overwrite the specified directory
  -p, --path=path      Path to look for stack file in repo
  -s, --start          Flag for starting the dev environment

See code: src\commands\repo.ts

Example Usage

This command will bootstrap this project to a folder in your home directory under stack/

npx @ajhenry/stack repo AJHenry/stack ~/stack

Why

After contributing to the JS open source community for awhile, I realized how often I had to look up exactly what package manager they were using (npm vs yarn), what other git submodules I needed, what the start command was (start vs dev vs build) for a simple change in the code. Not to mention how hard it can be to setup large monorepo projects like react and vue since they rely on many scripts to get things up and running.

My solution to this is basically an elegant bash script that can start dev environments dumb fast.

What about Docker?

Docker can do all this no problem, however I believe there are times where I'd like deeper control over my repo and dev tools rather than having everything abstracted by Docker.

What about bash scripts?

Bash scripts can also do all this work with some cavets, like leaving the developer to clone the repo, maybe even the submodules too. Then you will need to write the bash script for Windows too.

In fact, I still recommend having bash scripts that bootstrap a lot of the work in the repo. That way they can just be called by stack.

How it works

A .stack is a configuration and build file for a project. stack comes with a CLI that takes this configuration file and uses it to get a dev environment for the project up and running on your machine.

It can be thought of as a glorified init script.

Documentation

Stack Lifecycle

These are the methods and when they are executed

Note that if a step exits with a non 0 command and not listed as an exception, the command will fail and clean up the directory

• requires - Required The tools that are required for the install/start steps
• install - Required - Steps for installing the program, the entry point
• postinstall - optional - Steps that are run after install
• postinstallmsg - optional - Message that is displayed after postinstall
• start - optional - Steps for starting the development server
  • Can be ignored when --start flag is passed false

Stack File Documentation

# Name of the stack script
# Optional
name: Stack Project Starter

# Version of the stack generator to use
# Optional
version: 0.1.0

# Requires are the list of commands needed for this stack to work
# Optional
# Accepts the following types
#   - string[]
requires:
  - git
  - npm

# Install is a list of commands needed to install the dev environment
# Required
# Accepts the following types
#   - string
# ---
#   - cmd: string
# ---
#   - message: string
install:
  - git clone https://github.com/AJHenry/stack.git .
  - yarn

# PostInstall is a list of commands that are run after install
# Optional
# Accepts the following types
#   - string
# ---
#   - cmd: string
# ---
#   - message: string
postinstall:
  - yarn link


# PostInstallMsg is a message that prints out after postinstall
# Optional
# Accepts the following types
#   - string
postinstallmsg: To run a command, use ./bin/run <command>


# Start is command that starts the development server
# Required
# Accepts the following types
#   - string
# ---
#   - cmd: string
# ---
#   - message: string
start:
  - stack -h

Using common stacks

If a project doesn't have a stack file defined for it, you can use built in stack files that represent common patterns for getting projects up and running

Supported common stacks

• npm-start
• yarn-start

You can use the --common|-c flag to pass in a common stack

Example npm start Command

stack repo AJHenry/serverless-workshop --common npm-start

Examples

Here are some examples of .stack files to help you get started

Example .stack file

Here is an example of a stack file that creates a tailwind next starter + server.

name: Tailwind Next Starter
version: 0.1

requires:
  - npm
  - git

install:
  - git clone https://github.com/jpedroschmitz/typescript-nextjs-starter.git .
  - npm i
  - npm i tailwindcss@latest postcss@latest autoprefixer@latest
  - npx tailwindcss init -p

start:
  - npm run dev

License

MIT