• Getting Set Up

    Installing the repository

    To help you get set up, follow this checklist:

    1. Set up a Github account (add your buttonschool.com email under Settings -> Emails if you have an account already)
    2. Ask Nevan (or another admin) for access to the repo, from your account
    3. Install homebrew on your computer
    4. Install VS Code (we recommend using Homebrew: brew install --cask visual-studio-code, or download from code.visualstudio.com)
    5. If you don’t have one, make a directory for projects on your computer (we recommend ~/projects for easy access)
    6. In that directory, clone the buttonschool repo (git clone https://github.com/buttonschool/buttonschool.git)
    7. Open the repo in VS Code using the command line (code .)

    Running the setup script

    Once you’ve cloned the repository, run the setup script to install dependencies and configure your environment:

    chmod +x setup.sh && ./setup.sh

    This script will:

    • Install required packages from the Brewfile (including git, node, python, pnpm, and development tools)
    • Install all pnpm dependencies for the workspace
    • Set up your development environment

    The setup script uses Homebrew to install system dependencies, so make sure Homebrew is installed first.

    Verifying your setup

    After running the setup script, verify everything is working:

    1. Check pnpm is installed: pnpm --version
    2. Verify dependencies are installed: pnpm install (should complete quickly if already installed)
    3. Test Chalkboard: pnpm chalk (should start a dev server)
    4. Test handbook preview: pnpm handbook (should start a dev server)

    If any of these fail, check the error messages and ensure all prerequisites from the checklist are installed.

    What’s in the repo?

    We have four main directories we work out of:

    • content
    • packages
    • lab
    • websites

    Content

    The bulk of our work happens in content—this is where we keep all our course materials and internal documentation.

    Packages

    The packages directory contains our internal tools and utilities, including Chalk, Workbench, Blueprint, and other development tools.

    Websites

    In the websites directory, we keep the source files for our public-facing websites, primarily buttonschool.com.

    Lab

    Think of lab as a playground or sandbox for trying out ideas. These could range from interactive exercises for learners to internal tools for building previews from .chalk files.

    We may eventually showcase some experimental work publicly—even while it’s still in progress. Successful experiments may graduate to full-blown tools.

    For more details on the repository structure, see Repository Structure.

    What’s next?

    Now that you’re set up, you might want to: