Project Structure

In this lesson we will walk through the structure of the react-project scaffolded by Vite in the previous lessons. Understanding what each file is responsible for will make it easier to navigate every lesson project in this course.

1.Directory layout

After creating the project, react-project/ contains the following files and folders:

1
react-project/
2
├── public/
3
│   ├── favicon.svg
4
│   └── icons.svg
5
├── src/
6
│   ├── assets/
7
│   │   ├── hero.png
8
│   │   ├── react.svg
9
│   │   └── vite.svg
10
│   ├── App.css
11
│   ├── App.tsx
12
│   ├── index.css
13
│   └── main.tsx
14
├── .gitignore
15
├── README.md
16
├── eslint.config.js
17
├── index.html
18
├── package.json
19
├── tsconfig.json
20
├── tsconfig.app.json
21
├── tsconfig.node.json
22
└── vite.config.ts

We can group these into four categories: entry points, static assets, build and type configuration, and linting.

2.Entry points

These three files are the runtime entry chain of the application. Vite starts from index.html in the browser, which loads main.tsx, which in turn renders the root component App.tsx.

`index.html`

The single HTML page served to the browser. Unlike traditional bundlers, Vite treats index.html as the true entry point of the application — it is processed by Vite’s dev server and build pipeline.

The important line is <script type="module" src="/src/main.tsx">, which tells Vite to load the TypeScript entry module as a native ES module.

1
<!doctype html>
2
<html lang="en">
3
  <head>
4
    <meta charset="UTF-8" />
5
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
6
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
    <title>react-project</title>
8
  </head>
9
  <body>
10
    <div id="root"></div>
11
    <script type="module" src="/src/main.tsx"></script>
12
  </body>
13
</html>

`src/main.tsx`

The JavaScript/TypeScript entry point. It imports the global stylesheet, mounts the React application into the #root DOM node declared in index.html, and wraps it in <StrictMode> to catch common mistakes during development.

1
import { StrictMode } from 'react'
2
import { createRoot } from 'react-dom/client'
3
import './index.css'
4
import App from './App.tsx'
5

6
createRoot(document.getElementById('root')!).render(
7
  <StrictMode>
8
    <App />
9
  </StrictMode>,
10
)

`src/App.tsx`

The root React component rendered by main.tsx. This is the file you edit first to start building your UI — Vite’s Hot Module Replacement will reflect changes in the browser instantly without a full page reload.

3.Static assets

React supports two different ways of referencing static files, each with its own location.

`public/` — served as-is

Files placed in public/ are copied to the root of the build output without processing and are referenced by an absolute URL starting with /.

Use this folder for files that must keep a stable, predictable URL — for example favicon.svg (referenced from index.html via /favicon.svg) or icons.svg (referenced from components via <use href="/icons.svg#...">).

Because files here are not processed by the bundler, they are not hashed and can be cached aggressively by a CDN.

`src/assets/` — imported as modules

Files placed under src/assets/ are imported from code like any other module:

1
import reactLogo from './assets/react.svg'

Vite rewrites the import into a URL and, for production, emits the asset with a content-based hash in its filename. This gives you automatic cache-busting and lets the bundler eliminate unused assets via tree-shaking.

Rule of thumb: if an asset is referenced from a component, put it in src/assets/; if it must be reachable by a fixed URL, put it in public/.

4.Build and type configuration

These files configure Vite and the TypeScript compiler.

`package.json`

Declares the project name, scripts, and dependencies. In a workspace setup (see the previous lesson), dependency versions are set to "*" and resolved from the workspace root.

The relevant scripts are:

bun run dev — start the Vite dev server with HMR
bun run build — type-check with tsc -b and produce a production build
bun run preview — serve the production build locally
bun run lint — run ESLint across the project

`vite.config.ts`

The Vite configuration file. By default it only registers the @vitejs/plugin-react plugin, which enables JSX compilation and Fast Refresh during development.

This is where you would later add path aliases, proxy rules, or additional plugins.

1
import { defineConfig } from 'vite'
2
import react from '@vitejs/plugin-react'
3

4
// https://vite.dev/config/
5
export default defineConfig({
6
  plugins: [react()],
7
})

`tsconfig.json` — the project root config

A small file that uses TypeScript project references to split the type-checking into two independent sub-projects: one for application code, one for build-time Node.js code. It contains no compiler options itself.

1
{
2
  "files": [],
3
  "references": [
4
    { "path": "./tsconfig.app.json" },
5
    { "path": "./tsconfig.node.json" }
6
  ]
7
}

`tsconfig.app.json` — application code

The config used when type-checking everything under src/. It targets modern browsers (ES2023 + DOM types), enables strict checks, and is tuned for a bundler ("moduleResolution": "bundler", "noEmit": true) — TypeScript only type-checks, Vite/Rollup handles the actual code generation.

1
{
2
  "compilerOptions": {
3
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
4
    "target": "ES2023",
5
    "useDefineForClassFields": true,
6
    "lib": ["ES2023", "DOM", "DOM.Iterable"],
7
    "module": "ESNext",
8
    "types": ["vite/client"],
9
    "skipLibCheck": true,
10

11
    /* Bundler mode */
12
    "moduleResolution": "bundler",
13
    "allowImportingTsExtensions": true,
14
    "verbatimModuleSyntax": true,
15
    "moduleDetection": "force",
16
    "noEmit": true,
17
    "jsx": "react-jsx",
18

19
    /* Linting */
20
    "strict": true,
21
    "noUnusedLocals": true,
22
    "noUnusedParameters": true,
23
    "erasableSyntaxOnly": true,
24
    "noFallthroughCasesInSwitch": true,
25
    "noUncheckedSideEffectImports": true
26
  },
27
  "include": ["src"]
28
}

`tsconfig.node.json` — build-time code

A separate config used to type-check files that run in Node.js during the build — primarily vite.config.ts. It uses Node’s @types/node typings instead of DOM types, so browser globals are not accidentally available in build configuration.

1
{
2
  "compilerOptions": {
3
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
4
    "target": "ES2023",
5
    "lib": ["ES2023"],
6
    "module": "ESNext",
7
    "types": ["node"],
8
    "skipLibCheck": true,
9

10
    /* Bundler mode */
11
    "moduleResolution": "bundler",
12
    "allowImportingTsExtensions": true,
13
    "verbatimModuleSyntax": true,
14
    "moduleDetection": "force",
15
    "noEmit": true,
16

17
    /* Linting */
18
    "strict": true,
19
    "noUnusedLocals": true,
20
    "noUnusedParameters": true,
21
    "erasableSyntaxOnly": true,
22
    "noFallthroughCasesInSwitch": true,
23
    "noUncheckedSideEffectImports": true
24
  },
25
  "include": ["vite.config.ts"]
26
}

5.Linting

`eslint.config.js`

ESLint’s modern flat configuration file. The template composes four rule sets:

@eslint/js — baseline JavaScript rules
typescript-eslint — TypeScript-aware rules
eslint-plugin-react-hooks — enforces the Rules of Hooks
eslint-plugin-react-refresh — warns about patterns that break Fast Refresh in Vite

The dist/ folder is globally ignored so build artefacts are not linted.

1
import js from '@eslint/js'
2
import globals from 'globals'
3
import reactHooks from 'eslint-plugin-react-hooks'
4
import reactRefresh from 'eslint-plugin-react-refresh'
5
import tseslint from 'typescript-eslint'
6
import { defineConfig, globalIgnores } from 'eslint/config'
7

8
export default defineConfig([
9
  globalIgnores(['dist']),
10
  {
11
    files: ['**/*.{ts,tsx}'],
12
    extends: [
13
      js.configs.recommended,
14
      tseslint.configs.recommended,
15
      reactHooks.configs.flat.recommended,
16
      reactRefresh.configs.vite,
17
    ],
18
    languageOptions: {
19
      ecmaVersion: 2020,
20
      globals: globals.browser,
21
    },
22
  },
23
])

6.Miscellaneous

.gitignore — standard ignore list for a Node/Vite project (node_modules, dist, local env files, editor folders).
README.md — template documentation generated by Vite with hints on enabling type-aware lint rules and switching between React plugins.