Integrating Capacitor with Bun and Turborepo

Welcome back. In our previous lesson, we mapped out the conceptual territory of a Capacitor project, identifying the roles of the capacitor.config.ts file, the web build directory, and the native iOS/Android projects. You now have a solid mental model of the project's key structural components.

Today, we transition from concept to execution. Our objective is to take the first concrete step in adapting your monorepo: installing the necessary Capacitor tools. We will add Capacitor's core library and its Command-Line Interface (CLI) directly into your bun + Turborepo workspace. This lesson will focus on using bun for package management and bunx for running commands, fully aligning with your preferred development environment.

1. The Two Essential Packages: Core and CLI

Before we install anything, it's important to distinguish between the two primary packages you'll be adding. They serve distinct purposes:

• @capacitor/core: This is the runtime library. It provides the API that your web application will use to interact with native functionality. For example, when you want to access the device camera or check the network status, you will import functions directly from this package into your React components. As such, it's a production dependency.
• @capacitor/cli: This is the command-line tool that provides the cap command. You'll use it to initialize your project, add native platforms (iOS/Android), synchronize your web assets, and run your app on simulators and devices. Since it's a tool used during development and not part of the final app bundle, it should be installed as a development dependency.

In your Turborepo setup, we will install both of these packages at the root. This ensures that the CLI is available to orchestrate tasks across your entire workspace, which will be beneficial when we define pipeline scripts in turbo.json later on.

2. Installing Dependencies with bun

Your preferred package manager, bun, makes this process straightforward. We will use the bun add command. The -d flag is used to specify a development dependency, which is the correct scope for @capacitor/cli.

Execute the following commands from the root directory of your Turborepo:

# Add the runtime library as a production dependency
bun add @capacitor/core

# Add the command-line interface as a development dependency
bun add -d @capacitor/cli

After running these commands, you should see @capacitor/core added to the dependencies and @capacitor/cli added to the devDependencies in your root package.json file. bun's workspace support, which you can read about in its official documentation, ensures these packages are correctly installed and linked within your monorepo structure.

The following blog post from Capgo provides a practical walkthrough of this process. While it's written for a Next.js application, the initial Capacitor installation steps are identical for any web framework.

3. Verifying the Installation with bunx

With @capacitor/cli installed, your project now has access to the cap executable. However, it's not globally installed on your system. To run it, we use bunx, Bun's equivalent of npx. bunx executes package binaries from your local node_modules directory.

To verify that everything is installed correctly, you can run the cap command with a --help flag. This should display the Capacitor CLI's help menu, listing all available commands.

Open your terminal at the root of your monorepo and run:

bunx cap --help

If the installation was successful, you will see output that looks something like this, confirming that the CLI is ready to use:

  Capacitor CLI

  Usage:

    $ cap <command> [options]

  Commands:

    add, a <platform> [version] ........ Add a native platform project
    ...

Seeing this output is the milestone for this lesson. It confirms that the Capacitor tooling is correctly integrated into your development environment and ready for the next step.

Conclusion

In this lesson, you have taken the pivotal first step of integrating Capacitor into your project. You've learned to distinguish between @capacitor/core and @capacitor/cli, and you've successfully installed them into your Turborepo's root using bun. Critically, you've also verified that you can execute Capacitor CLI commands using bunx.

Our key takeaways are:

• @capacitor/core is the runtime API for your web app.
• @capacitor/cli provides the cap command for development tasks.
• Dependencies are managed at the monorepo root using bun add.
• CLI commands are executed using bunx cap <command>.

With the tools in place, we are now ready to initialize Capacitor within your project. In the next lesson, we will run bunx cap init to generate the capacitor.config.ts file, formally defining your web app's bridge to the native world.