` — lives there and nowhere else. 3. **Entry Points Define Reachability**: Tree-shaking is reachability analysis from the entry. Pick the wrong entry, or funnel every import through a fat barrel, and the bundler can no longer prove unused exports are dead. ## Best Practices ✅ **DO**: - Ship an index file in every served directory, or disable directory listing (`Options -Indexes`, `autoindex off`) - Add SPA history fallback (`try_files $uri $uri/ /index.html`) so deep routes survive a refresh - Keep the host document minimal: `charset` first, viewport, title/description, one mount node, one deferred module script - Use barrels for *public* surfaces (a feature folder, a component library) and direct paths inside a folder - Declare `exports` (plus `main`/`module`/`types` for legacy resolvers) and verify with `npm pack` before publishing - Pick one canonical URL form (with or without trailing slash) and 301 the other ❌ **DON'T**: - Import a sibling through the barrel that re-exports it — that is a circular import and yields `undefined` at module-init time - Put render-blocking `` / synchronous ` ``` `type="module"` is deferred by definition, so parsing is never blocked. A crawler that does not execute JS sees only the empty `#root` — that is the SEO trade-off SSR/SSG exists to solve. ### Directory Resolution and Barrels ```javascript // src/ui/atoms/index.js — a barrel over a public surface export { default as Button } from './Button/Button.component'; export { default as Input } from './Input/Input.component'; // Consumers resolve the directory, not the file import { Button, Input } from '../ui/atoms'; // → ../ui/atoms/index.js // ❌ Inside Button.component.jsx — cycles back through the mid-evaluation barrel import { Input } from '../index'; // ✅ Import the sibling directly import Input from '../Input/Input.component'; ``` Node's order is: exact file → `/package.json` `main` → `/index.js` → throw `Cannot find module`. ### Package Entry Points ```json { "name": "my-library", "exports": { ".": { "import": "./dist/index.mjs", "require": "./dist/index.cjs" }, "./utils": "./dist/utils/index.mjs" }, "main": "./dist/index.cjs", "module": "./dist/index.mjs", "types": "./dist/index.d.ts", "files": ["dist"] } ``` When `exports` is present it wins over `main`/`module` *and* blocks unlisted deep imports. Resolution priority: `exports` → `module` (bundlers) → `main` → `index.js`. ### In the elegant templates `templates/chota-react-saga` uses the Vite convention: `index.html` at the project root is the build entry, not a `public/` asset. ```html

``` ```jsx // src/index.jsx import { createRoot } from 'react-dom/client'; import App from './App'; const root = createRoot(document.getElementById('root')); root.render(); ``` `vite.config.js` sets `build: { outDir: 'build' }` and `base: './'` — relative asset URLs, so the built `build/index.html` can be served from a subdirectory (which is how `demos.sh` publishes it under `docs/demos/`). The templates also lean on directory resolution for their own layers: `App.jsx` does `import HomePage from './pages'` (→ `src/pages/index.jsx`) and `import store from './state'` (→ `src/state/index.js`). Note there is no `main` field in a template's `package.json` — these are apps, not libraries, so the bundler entry is the only entry that matters. ## Related Terminologies - **App Shell** (Server) - The cached skeleton the host document paints first - **SEO** (Server) - An empty `#root` is what crawlers see without SSR/SSG - **SSR / SSG** (Server) - Fill `index.html` with real markup per route - **PWA** (Server) - Manifest and service-worker registration hang off the host document - **Atom / Molecule** (UI) - Barrel `index.js` files expose these layers ## Quality Gates - [ ] Every served directory has an index file, or listing is disabled - [ ] SPA deep routes fall back to `index.html` (no 404 on refresh) - [ ] Host document has `charset` first, viewport, title, description, and one mount node - [ ] Scripts are `type="module"` or `defer`; no render-blocking `` chains - [ ] Barrels never import their own siblings back through themselves - [ ] Published packages declare `exports`/`main` pointing at emitted build output **Source**: `/docs/server/index-file.md`