# Getting started

Flare is a TypeScript-first, GPU-rendered 2D engine for React Native and the web — one
codebase for animation, gamification, interactive UI, and games on iOS, Android, and the
browser. This page takes you from an empty directory to a running first frame.

<Aside type="note">
The `@flare-engine/*` scope is published restricted. Public, install-without-a-token access
lands with the OSS launch (target October 2026). Until then, an authed `.npmrc` is required —
see step 1. The engine repo is private until launch as well, so links into it (such as the
api-specs reference below) become reachable only once it's public.
</Aside>

<Steps>

1. **Install the engine.**

   Add the umbrella package (`@flare-engine/engine`), which re-exports the lower layers and
   provides `createGame()`. Most apps also want the React bindings (`<GameView>`, hooks,
   virtual controls):

   <Tabs syncKey="pkg">
   <TabItem label="bun">
   ```bash
   bun add @flare-engine/engine @flare-engine/react
   ```
   </TabItem>
   <TabItem label="npm">
   ```bash
   npm install @flare-engine/engine @flare-engine/react
   ```
   </TabItem>
   <TabItem label="pnpm">
   ```bash
   pnpm add @flare-engine/engine @flare-engine/react
   ```
   </TabItem>
   <TabItem label="yarn">
   ```bash
   yarn add @flare-engine/engine @flare-engine/react
   ```
   </TabItem>
   </Tabs>

   Because the scope is restricted, point `@flare-engine` at npm with an auth token first.
   Create an `.npmrc` next to your `package.json`:

   ```ini
   @flare-engine:registry=https://registry.npmjs.org/
   //registry.npmjs.org/:_authToken=${NPM_TOKEN}
   ```

   Depend with a caret range so patch releases flow in: `^0.2.1`.

   Prefer to start from a runnable template instead? Scaffold an Expo + Flare app — it ships
   a minimal scene and HUD:

   ```bash
   npm create flare-app@latest my-game
   ```

   Templates: `blank` (empty scene, `GameView` wired — the smallest starting point),
   `topdown` (4-dir movement, tilemap, camera follow), and `shmup` (auto-fire player, enemy
   spawner, HUD).

2. **Create a program.**

   The front door is `<GameView>` — the React host that owns the Skia canvas, the
   fixed-timestep loop, and input. It lives in `@flare-engine/react` and is re-exported from
   the `@flare-engine/engine` umbrella, so you can import it from either. Mount it, and in
   `onReady` start the loop. This is the `blank` starter verbatim:

   ```tsx
   import { GameView, type GameContextValue } from "@flare-engine/engine";
   import type React from "react";
   import { StyleSheet, View } from "react-native";

   function handleReady(ctx: GameContextValue): void {
     ctx.loop.start();
   }

   export function App(): React.ReactElement {
     return (
       <View style={styles.root}>
         <GameView onReady={handleReady} style={styles.game} />
       </View>
     );
   }

   const styles = StyleSheet.create({
     root: { flex: 1, backgroundColor: "#000" },
     game: { flex: 1 },
   });
   ```

   `ctx` is the game context — `{ world, camera, input, audio, assets, scenes, loop,
   renderer, batch }` — your entry point for spawning entities, registering scenes, and
   loading assets.

3. **Render the first frame.**

   `ctx.loop.start()` begins the fixed-timestep loop; the render system flushes the sprite
   batch once per frame, and `<GameView>` draws it to the Skia canvas. The empty scene above
   already produces a frame (a cleared canvas). To put something on screen, spawn an entity
   with a `Position` and a `Sprite` from `onReady` and drive it from the loop — see the
   `topdown` template for a worked example that adds a component and camera-follows it.

   <Aside type="tip">
   Pre-create ECS queries in setup; never call `world.query()` per frame — it allocates on
   the hot path.
   </Aside>

   The canonical, runnable first-scene code lives in the engine repo's starter templates
   (`packages/create-flare-app/templates/`) and the
   [api-specs reference](https://github.com/grzott/flare-engine/blob/main/docs/design/api-specs.md).
   This site links rather than forks it, so the API contract stays single-sourced.

4. **Run on web and native.**

   The same source targets both. Through React Native + Expo you run on iOS and Android,
   where rendering goes through `@shopify/react-native-skia`; on the web the renderer is
   CanvasKit WASM, shipped as `@flare-engine/render-web`. (This site's hero currently runs a local
   precursor of it; the published-package dogfood is in progress.) The scaffolded app (step 1) wires
   the Expo dev scripts for you — start it
   from your project the usual way and pick a target (iOS, Android, or web).

</Steps>

## Next steps

- [Concepts → Architecture](/concepts/architecture) — the layered package model, native vs
  web backends, and the dependency-flow rule.
- [Guides → Overview](/guides/overview) — where to go next once the first frame is on screen.