Setup Blutui Courier

Blutui Courier is an essential cross-platform command-line interface (CLI) tool designed to streamline the local development and deployment of your Blutui projects. It allows you to seamlessly pull your project files from the Blutui platform, make local modifications, and push those changes back.

Getting Started with Blutui Courier

To begin using Blutui Courier, you first need to install it on your local machine. Please follow the comprehensive getting started with Blutui Courier guide. This guide provides detailed instructions for installation, ensuring you have Courier set up correctly for your operating system.

Courier needs to be installed before you can scaffold a new project. Make sure you have followed the installation instructions for your operating system.

Initializing Your Local Project with Courier

Once Blutui Courier is successfully installed, you can use it to scaffold a new project directly on your local machine. This sets up the foundational file structure and necessary configurations based on a chosen Canvas.

Open your terminal or command prompt

Run the courier create command

You can pass a project handle directly, or run courier create on its own and Courier will prompt you for one.

-> ~ courier create
? What is your project handle? › [project-handle]

Choose your Canvas

Once you've entered a project handle, Courier presents a list of available Canvases. Canvases are pre-configured project templates that provide a starting point for your development.

✔ What is your project handle? … [project-handle]
? Which Canvas would you like to use?
  | base
  | Bare bones Canvas for Blutui.

  | tailwindcss
  | Bare bones Canvas with Tailwind CSS for Blutui.

  | tailwindcss-js
  | Bare bones Canvas with Tailwind CSS + Parcel.js for Blutui.

  | headless-nextjs-blank
  | Bare bones Next.js Canvas for Blutui Headless.

The available Canvases include:

base: A minimal project structure.

tailwindcss: A project scaffold configured with Tailwind CSS.

tailwindcss-js: A project scaffold that includes Tailwind CSS along with a JavaScript compiler Parcel for efficient asset bundling.

headless-nextjs-blank: A minimal Next.js project setup without any opinionated styles or configurations.

For a complete and up-to-date list of all available Canvases, including community-contributed options, please visit the Blutui Canvases GitHub repository.

You can skip this prompt by passing the Canvas directly, for example courier create [project-handle] --canvas tailwindcss-js.

If you'd like to share a canvas that would help the wider Blutui community, submit a pull request to the Blutui Canvases GitHub repository to make it available to all users.

Choose whether to install Blutui Context

Courier then asks if you'd like to install Blutui Context, which configures the Blutui MCP server and installs the Blutui Skills for your AI coding assistant.

? Do you want to install Blutui Context to improve AI assisted coding?
  (•) Yes
  ( ) No

  (y/n, press q to skip)

If you choose Yes, Courier will ask which MCP client you're using (Claude Code, Cursor, Visual Studio Code, Codex, or OpenCode) and configure it automatically. You can pre-answer both questions with the --context and --client flags.

Let Courier scaffold your project

Courier now does the work for you: it downloads the Canvas, initializes Courier by generating a courier.json file in the new project directory, and configures Blutui Context if you opted in. There's no separate courier init step to run.

✔ What is your project handle? … [project-handle]
✔ Which Canvas would you like to use? … tailwindcss-js
✔ Do you want to install Blutui Context to improve AI assisted coding? … Yes

✔ Success! A new project was created at ./[project-handle]

  Blutui Context installed:
  • MCP server  .mcp.json
  • Skills      blutui/context

  Start building your new project by typing:

  $ cd [project-handle]

Understanding Cassettes

By default the generated courier.json uses the default Cassette. Cassettes are Blutui's method for managing different versions of a website. For example, if you have a main website but also need distinct versions for events like Christmas or Halloween, cassettes allow you to easily switch between these different site UIs. To scaffold against a specific Cassette, pass the --cassette flag:

courier create [project-handle] --cassette [cassette-name]

We'll delve deeper into Cassettes later in the documentation.

What's Next? Understanding the Blutui Folder Structure

Once you've scaffolded your project using Blutui Courier, you'll find a well-organized folder structure designed to separate your compiled output from your front-end logic. Navigating this structure is key to efficient development.

On this page