> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Base44 frontend: Web app, Vite SPA

> source commit is in /SOURCE_COMMIT at the repository root. Edits here are overwritten by

> [!WARNING]
>
> This page is part of an AI coding agent skill and is written for agents, not humans. For the human-readable Base44 docs, see the [developer documentation](https://docs.base44.com/developers).

# Base44 frontend: Web app, Vite SPA

You develop pages and, when needed, components or the app's layout.

\<code\_conventions>

* Before editing, account for dependent files, earlier changes, and the user's own edits.
* Export every page/component as default, named same as its file.
* shadcn/ui from @/components/ui; Tailwind CSS for styling.
* Icons: lucide-react only, only icons that exist — a nonexistent or unimported icon breaks the whole app.
* Every import must resolve to a real file or package.
* URL params: const urlParams = new URLSearchParams(window\.location.search).
* Handle just-registered users with nothing saved on the user entity yet.
* Entities: always the full JSON schema — no comments/placeholders; it replaces the stored schema.
* Let errors bubble up — no try/catch unless asked — an unhandled error surfaces in the preview and the app logs, where you can see and fix it. Exception: user-facing form/auth flows catch and show inline errors (that behavior is the feature).
  \</code\_conventions>

\<available\_packages>
\<packages\_installed>
Only these frontend packages are installed: React; tailwind css; shadcn/ui (all components); lucide-react; moment; recharts; react-quill-new; react-hook-form; react-router-dom; date-fns; lodash; react-markdown; framer-motion; three.js (3d models/games); react-leaflet (maps); @hello-pangea/dnd (drag and drop); @tanstack/react-query (data fetching/query state); @/api/base44Client (pre initialized sdk); @/utils.
Never use any other library — only this list plus shadcn components in @/components/ui/; anything else breaks the app.
\</packages\_installed>

\<entities\_package>
The entity SDK is documented in the `base44-platform-entities` skill.
\</entities\_package>

\<integrations\_package>
The integrations SDK (InvokeLLM, SendEmail, file uploads) is documented in the `base44-platform-integrations-sdk` skill.
\</integrations\_package>

\<analytics\_package>
Analytics tracking is documented in the `base44-platform-integrations-sdk` skill.
\</analytics\_package>
\</available\_packages>

\<app\_router>
src/App.jsx is the application router — a page without a Route there is unreachable. On page add/remove, update src/App.jsx in the same change: import near "// Add page imports here" + Route inside Routes.

\<navigation>
\<Link to="/path"> with route paths from src/App.jsx, not createPageUrl.
\</navigation>

\<layouts>
No automatic layout wrapping — don't create a root-level src/Layout.jsx. Shared layouts: a component (e.g., src/components/Layout.jsx) with React Router's \<Outlet>, used as a layout route:

```jsx theme={null}
import { Outlet } from 'react-router-dom';
export default function Layout() { return <div><Sidebar /><main><Outlet /></main></div>; }
// src/App.jsx
<Route element={<Layout />}>
  <Route path="/" element={<Home />} />
</Route>
```

\</layouts>

\<routing\_conventions>

* Main/home page on "/" only — no second route under the component name (both "/" and "/Home").
* Changing the main page: the "/" route in src/App.jsx is the source of truth — no platform setting; point "/" at the desired component and import it at the top (don't send the user to dashboard settings).
* Unknown paths: keep `<Route path="*" element={<PageNotFound />} />` last — never point it at Home. Every not-found screen (that page, and a detail page whose item does not exist — never on a failed load) appends `<meta name="prerender-status-code" content="404">` to `document.head` in a `useEffect` and removes it on cleanup; crawlers then get a real 404. Only once loading has finished — a real page that flashes "not found" while its data loads would be served as a 404.
  \</routing\_conventions>

Keep these framework wrappers in src/App.jsx intact — auth, data fetching, routing, and toasts run through them:

* \<AuthProvider>, \<QueryClientProvider>, \<BrowserRouter>/\<Router>, \<Toaster />
* AuthenticatedApp and its auth logic (loading states, UserNotRegisteredError)
* ProtectedRoute from @/components/ProtectedRoute for per-route auth guarding

\</app\_router>

\<tailwind\_class\_names>
Write Tailwind classes as literal strings (const maps/arrays included) — the build purges anything not found as a literal substring in source; dynamic names (`bg-${color}-500`, `"bg-" + shade`) silently disappear. `safelist` in `tailwind.config.js` only for runtime-sourced values (entity records, API responses, user input), never for classes in source.
\</tailwind\_class\_names>

\<prebuilt\_components>
\<index\_html>
index.html — for page title, meta tags (SEO, Open Graph), external scripts (Analytics, AdSense), favicon, custom fonts. Always preserve: `<head>` (runtime script injection), `<div id="root"></div>` (React mount), `<script type="module" src="/src/main.jsx"></script>` (entry). Once customized, served as-is — no automatic injections (SEO/social tags, canonical URLs, favicons).
\</index\_html>
\</prebuilt\_components>

\<styling\_instructions>
Build beautiful, clean, modern, fully featured, production-worthy, responsive (mobile + desktop) apps.

Stock photos from Unsplash where appropriate — only valid URLs you know exist; link in image tags, don't download.

\<content\_image\_component>
Render every content image (user uploads, generated images — any media.base44.com / static.wixstatic.com URL) with the `Image` component from `@/components/ui/image`, never a plain `<img>` — it serves the image resized to its container, encoded for the browser, with responsive srcset. Size the box via `className`; `fittingType="fill"` (default, crops) or `"fit"` (contains); optional `focalPointX`/`focalPointY` (0–1) anchor the crop. Other hosts and SVGs pass through unchanged, so it is always safe.
\</content\_image\_component>

Show loading indicators while integration calls are in flight.
Color token syntax must match its consumer: `hsl(var(--token))` requires HSL channels such as `0 0% 100%`; an RGB tuple such as `248 250 252` requires `rgb(var(--token))`. Never put unitless RGB channels into an HSL token.

\<tokens\_based\_design\_system>

* `src/index.css` owns token values; `tailwind.config.js` maps tokens to Tailwind classes. Theme changes: update values in `src/index.css`, use mapped classes in JSX.
* Colors: update both `:root` and `.dark`.
* Fonts: `@import url('...')` at top of `src/index.css`, before `@tailwind base;`; update font role tokens (`--font-heading`, `--font-body`, `--font-display`), adding them to `src/index.css`/`tailwind.config.js` if missing.
* JSX: mapped token classes (`bg-primary`, `font-heading`, `font-body`, `font-display`); no hardcoded values (`bg-[#ffffff]`, `bg-white`, `font-[Inter]`, inline `style={{ background: "#ffffff", fontFamily: "Inter" }}`).
* New custom tokens only when semantic tokens aren't enough and the value is reused: define under `:root` + `.dark` in `src/index.css`, map in `tailwind.config.js`, use the generated class.
  \</tokens\_based\_design\_system>

\</styling\_instructions>

\<componentization>

* Small focused files: components of 50 lines or less; every new component/page gets its own new file, never added to an existing one.
* Break oversized pages into components yourself — no need to ask.
  \</componentization>

\<working\_with\_files>
You work on the app's sandbox files directly: read, write and edit them by path and run shell commands, through the Base44 MCP sandbox tools or the `base44 sandbox` CLI.

* Entity files (`base44/entities/*.jsonc`) are stored as objects: always write the complete schema, never a partial patch or placeholders.
* Writes are committed automatically a few seconds after the change and synced into the platform: a resource file (entity, agent, function, workflow) is live once written; there is no deploy step.
* Only checkpoints appear in the builder's version history. Create one with the MCP `create_checkpoint` tool (`base44 sandbox checkpoint` in the CLI) when you finish a unit of work and before you stop; the next Restore in the builder discards everything after the last checkpoint.
* Verify with the project's own commands (`npm run build`, lint) before finishing.
  \</working\_with\_files>

\<npm\_package\_installation>
Install only when the user explicitly requests a package by name or npmjs.com URL — the exact package, no substitutes; otherwise use installed packages. Check the installed list first, then install from the sandbox shell (`npm install <package>@^<version>`): stable versions, caret (^) for compatible updates. Remove a package the user no longer wants with `npm uninstall`. Never uninstall @base44/sdk or @base44/vite-plugin — the platform requires them.
\</npm\_package\_installation>


## Related topics

- [Introduction](https://docs.base44.com/developers/app-code/overview/introduction.md)
- [Base44 Developer Platform](https://docs.base44.com/developers/home.md)
- [Base44 developer tools](https://docs.base44.com/documentation/building-your-app/developer-tools.md)
- [Local development setup](https://docs.base44.com/developers/backend/overview/local-dev/get-started.md)
- [React Quickstart](https://docs.base44.com/developers/backend/quickstart/frameworks/quickstart-with-react.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.