Quickstart Guide

Welcome to the ZeroStack Quickstart guide! This guide is designed for developers who are just getting started. Follow these steps precisely to set up your environment and launch your first project.

Note

This guide currently supports macOS only. Support for Windows and Linux is coming soon!

Before you begin

Make sure you’ve reviewed the prerequisites, including setting up your Cloudflare and GitHub accounts.

1. Open Your Terminal

   The Terminal is where you will type commands to control your computer and build your apps.

   • How to find it: Press Cmd + Space on your keyboard, type “Terminal” (or “Ghostty” if you have it installed), and press Enter.
   • You should see a window with a blinking cursor. Keep this window open!

2. Set Up Your Environment (Dotfiles)

   We use a standard set of configurations called “dotfiles” to make your terminal powerful and easy to use.

   Copy and paste this command into your terminal and press Enter:

   curl -L https://raw.githubusercontent.com/builtby-win/dotfiles/main/install.sh | bash

   What does this do? It downloads and runs a script that sets up your Zsh configuration, Git shortcuts, and other essential developer tools.

3. Purchase and GitHub Access

   You need access to our private templates (like zerostack) to create your apps.

   • Purchase ZeroStack: You must purchase a license to access the private repository. Click here to purchase ZeroStack.
   • GitHub Access: After purchase, ensure your GitHub account has been granted access to the builtby-win/zerostack repository.

4. GitHub Authentication

   You need to tell your terminal who you are on GitHub so it can download your new project. In your terminal, run this command:

   gh auth login

   • What to choose:
     • Account: GitHub.com
     • Preferred protocol: HTTPS
     • Authenticate: Login with a web browser
   • A browser window will open. Click “Authorize” to finish the login.

5. Create Your Application

   Now you are ready to start your project. Run the following command, replacing your-app-name with whatever you want to call your project:

   npx @builtby.win/cli your-app-name

   • Wait for it to finish: The CLI will check that you have access to the repository, download the template, and set up your new project folder.

6. Initialize Your Project

   Once the CLI is finished, you must enter your new project folder and run the setup command. Run these two commands in your terminal:

   cd your-app-name
   pnpm setup

   • What does pnpm setup do? This installs all the necessary packages and configures your local environment (like your database and authentication) for development.

7. Cloudflare & Deployment

   We use Cloudflare to host our applications. If you haven’t already, sign up for a free account.

   • Login to Cloudflare: Run this command in your terminal:

     npx wrangler login

   • Deploy: Push your app live to the internet (this performs a full production build and applies database migrations):

     pnpm deploy

   • GitHub CI/CD Integration: Automatically deploy your app every time you push to GitHub:

     1. Navigate to the Workers & Pages section on your Cloudflare Dashboard.
     2. Select the application you just deployed.
     3. Go to Settings > Builds & deployments > Git integration.
     4. Click Connect GitHub, select your account, and choose the repository you created.
     5. For more details, see the official Cloudflare Git Integration Guide.

Your app is now fully set up with automated deployments! You can find your live URL in the Cloudflare Dashboard.