# Project structure (https://docs.salla.dev/twilight/react/start/project-structure)



Read this when you open your new theme and wonder which files to touch.

<Callout title="Framework: TanStack Start">
  This page is written for TanStack Start, the default and currently supported framework. [See what depends on the framework](https://docs.salla.dev/twilight/react/start/frameworks).
</Callout>

A new theme is a copy of Salla's Raed theme, so you start from a full storefront. These are the parts that matter.

<Files>
  <Folder name="my-store">
    <Folder name="app">
      <Folder name="components" />

      <Folder name="hooks" />

      <Folder name="routes">
        <File name="__root.tsx" />
      </Folder>

      <Folder name="styles" />

      <File name="client.tsx" />

      <File name="hydrate.tsx" />

      <File name="router.tsx" />

      <File name="routes.ts" />

      <File name="routeTree.gen.ts" />

      <File name="start.ts" />
    </Folder>

    <Folder name="locales">
      <File name="ar.json" />

      <File name="en.json" />
    </Folder>

    <Folder name="public" />

    <File name="twilight.json" />

    <File name="vite.config.ts" />

    <File name="package.json" />
  </Folder>
</Files>

## The files you edit [#the-files-you-edit]

| File                            | What it does                                                                                                                                                                                                                                                                       |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vite.config.ts`                | Calls `twilightReact()` from `@salla.sa/twilight-theme-engine/vite`, which sets up rendering, routes and translations. You rarely change it. See [the Vite plugin](https://docs.salla.dev/twilight/react/local-development/vite-plugin).                                                                                |
| `app/start.ts`                  | Registers the engine's request middleware (`twilightMiddleware`, `earlyHintsMiddleware`) so every request knows its store and visitor.                                                                                                                                             |
| `app/client.tsx`                | The first script the browser runs. It calls `bootClient` from `@salla.sa/twilight-theme-engine/boot`, which loads `app/hydrate.tsx`; on the home and product pages it first waits for the main image to paint. See [Performance](https://docs.salla.dev/twilight/react/guide/performance#paint-the-first-screen-first). |
| `app/hydrate.tsx`               | Exports `hydrate()`, which hydrates the page with React's `hydrateRoot`.                                                                                                                                                                                                           |
| `app/router.tsx`                | Creates the router and registers your replacements for home blocks and your hooks.                                                                                                                                                                                                 |
| `app/routes/__root.tsx`         | The page shell: the `<html>` and `<body>`, the provider and your layout component.                                                                                                                                                                                                 |
| `app/routes.ts`                 | Lists your custom routes. A path here adds a page or replaces the engine's page for that path. See [Routes and pages](https://docs.salla.dev/twilight/react/guide/routes-and-pages).                                                                                                                                    |
| `app/components/`, `app/hooks/` | Your components, and the code that places UI into hook slots. See [Layout and components](https://docs.salla.dev/twilight/react/guide/layout-and-components) and [Hooks and slots](https://docs.salla.dev/twilight/react/guide/hooks-and-slots).                                                                                                             |
| `app/styles/`                   | Tailwind and SCSS. See [Styling](https://docs.salla.dev/twilight/react/guide/styling).                                                                                                                                                                                                                                  |
| `locales/*.json`                | Your translation overrides, one file per language.                                                                                                                                                                                                                                 |
| `twilight.json`                 | The manifest: theme name, features, merchant settings and home blocks. See [Settings](https://docs.salla.dev/twilight/react/guide/settings).                                                                                                                                                                            |
| `public/`                       | Static files served as they are.                                                                                                                                                                                                                                                   |

## The files you do not edit [#the-files-you-do-not-edit]

* `app/routeTree.gen.ts` is generated.
* Route files in `app/routes/` that start with `// @auto-generated` are generated from the engine's routes and are overwritten on the next build. Your own page files, the ones you point to from `app/routes.ts`, do not have that line and are yours.
* The product listings (`/products`, `/search`, a category, a tag, a brand's products) and `/reviews` are not generated into `app/routes/` at all: the engine serves them from its own copy. A file of the same name without the `// @auto-generated` line replaces the engine's.

<Callout type="warn">
  Do not hand-edit generated files. They are rewritten on the next build.
</Callout>

## Next [#next]

[How it works](https://docs.salla.dev/twilight/react/start/how-it-works): what happens between a customer's request and the page they see.