Project Structure

This chapter walks through the folders and files generated by Vite's react-ts template, then covers configuration and folder layouts that hold up as a project grows.

The default layout

my-app/
├── public/
│   └── vite.svg
├── src/
│   ├── assets/
│   │   └── react.svg
│   ├── App.css
│   ├── App.tsx
│   ├── index.css
│   └── main.tsx
├── eslint.config.js
├── index.html
├── package.json
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
└── vite.config.ts

index.html and main.tsx

Unlike many bundlers, Vite keeps index.html at the project root and treats it as the entry point. Starting from the src/main.tsx referenced by <script type="module">, it follows imports to load every module.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>my-app</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

main.tsx calls createRoot from react-dom/client to create a React root on the #root element and renders App into it. App-wide providers such as a router, a data-fetching client or a theme usually wrap the tree here as well.

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

package.json scripts

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  }
}

For speed, Vite only transpiles TypeScript and never type-checks it. That is why the build script runs tsc -b first and only calls vite build when there are no type errors. preview serves the build output locally so you can check it.

vite.config.ts and path aliases

To write @/components/Button instead of long relative paths like ../../components/Button, register the alias with both Vite and TypeScript.

import { fileURLToPath, URL } from "node:url";
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) },
  },
  server: { port: 3000 },
});

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

Add the paths entry to compilerOptions in tsconfig.app.json, which type-checks the app code. Using node:url in the config may require npm install -D @types/node.

Environment variables

Vite loads files such as .env, .env.local and .env.production from the project root. Only variables prefixed with VITE_ are exposed to client code, where you read them from import.meta.env.

# .env.local (keep this out of Git)
VITE_API_URL=http://localhost:8080

const apiUrl = import.meta.env.VITE_API_URL;
const isDev = import.meta.env.DEV;

These values are inlined into the bundle at build time, so anyone can read them. Never put secrets such as API keys into VITE_ variables; handle them on the server instead.

Organizing a growing project

React does not impose a folder structure. A small app is fine with a single src/components/; as it grows, grouping code by feature is a common approach.

• src/components/: shared components used across screens, such as buttons and modals
• src/features/<feature>/: the components, hooks and API calls that belong to one feature
• src/hooks/: custom hooks shared between features, such as useDebounce.ts
• src/lib/: UI-independent helpers and the API client
• src/pages/ or src/routes/: page-level components when you use a router

By convention, component files use PascalCase names like UserCard.tsx and hooks start with use, as in useUser.ts. For styling you can import global CSS, use CSS Modules (Button.module.css) for locally scoped class names, or add a tool such as Tailwind CSS.

Summary

• index.html is the entry point, and src/main.tsx mounts the React app into #root.
• npm run build type-checks with tsc -b and then bundles with vite build.
• Path aliases are registered in both vite.config.ts and tsconfig.app.json.
• VITE_ environment variables are public, so never store secrets in them.
• As the app grows, organize it by feature with consistent file naming.