@ajhenry/stack
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.0 • Public • Published


    stack

    A CLI to bootstrap dev environments lightning fast


    FeaturesHow To UseWhyDocumentationExamplesLicense

    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]

    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

    Install

    npm i @ajhenry/stack

    DownloadsWeekly Downloads

    1

    Version

    0.2.0

    License

    MIT

    Unpacked Size

    35.5 kB

    Total Files

    22

    Last publish

    Collaborators

    • ajhenry