Getting Started

---

Welcome! We’re excited you’ve decided to try Bloom. These series of tutorials will walk you through everything you need to start making beautiful interactive diagrams directly in React. This first chapter will lead you through creating a React app and installing Bloom. If you already have a React app set up, just install the npm package @penrose/bloom with your favorite package manager and move on to the next tutorial.

These tutorials expect that you have some proficiency with JavaScript and React, plus a teeny bit of linear algebra, though we’ll keep that to a minimum. They do not assume you have any experience with Penrose, though if you do, you’ll likely find the concepts familiar.

Creating a React App

You'll need node.js $\ge$ 18 and npm $\ge$ 8 before getting started, which you can find here. Once those are installed, create new React app as follows:

npm create vite@latest my-bloom-app -- --template react-ts
cd my-bloom-app
npm install

You should obviously change my-bloom-app to whatever makes sense for you. Finally, you can install the Bloom package and its dependencies. We highly recommend using TypeScript with Bloom, which is why we used the react-ts template above.

npm install @penrose/bloom

Vite Plugins

If you're using vite with Bloom (like in this tutorial), you'll need the vite-plugin-top-level-await plugin to support our automatic differentiation engine, Rose:

npm install vite-plugin-top-level-await

You must also update your vite.config.ts:

import { defineConfig } from "vite";
import topLevelAwait from "vite-plugin-top-level-await";

export default defineConfig({
  // ...
  plugins: [/*...,*/ topLevelAwait()],
  optimizeDeps: { exclude: ["rose"] },
});

Creating a component

At this point you'll probably want to remove all the template nonsense from your directory:

(please make sure you're in the root of your project directory before running this command!)

rm -rf public/ src/*.css src/App.tsx src/assets/

You'll also want to remove the import "./index.css"; statement from src/main.tsx.

Now create a new App.tsx file in the src/ directory with the following content:

import { Renderer } from "@penrose/bloom";

const App = () => {
  return <Renderer diagram={null} />;
};

export default App;

If everything is set up correctly, running npm run dev should now render, well, nothing. In the next chapter, we'll start building our first diagram. From here, we'll assume some proficiency with React, so if you need a refresher you check out their excellent tutorial here.