#Frontend Overview

#Table of Contents

• What Vext Frontend Is
• Create a Full-stack Project
• Project Structure
• First Page
• Current Capabilities
• Reading Paths

#What Vext Frontend Is

Vext Frontend is the built-in full-stack React 19 experience for Vext projects. The URL still belongs to src/routes/**; the route handler prepares server data and calls res.render() to render a page from src/frontend/pages/**.

Use it when one app needs APIs, server-rendered pages, and browser interaction. A page request follows this path:

Browser GET / → server route → prepare props → res.render("index", props)
              → React server HTML → browser hydration (when enabled)

Page components also run during SSR, so reading browser globals such as window while rendering can fail. Keep database and upstream calls in routes/services. Props are exposed to the browser and should contain only data the page needs.

Use --template api --frontend none when the project is API-only.

#Create a Full-stack Project

npx vextjs create my-app
cd my-app
npm run dev

Install a Node.js and npm version satisfying the current Vext package; see the general quick start. The default command generates a TypeScript full-stack React app and runs npm install automatically. If installation fails or --skip-install is used, run npm install in the project before starting. Open the address printed by the terminal, normally http://localhost:3000/. For an API-only app:

npx vextjs create my-api --template api --frontend none

#Project Structure

These are the main files in the default TypeScript full-stack starter; see Project Structure for configuration, types, and generated output.

src/
  config/
    default.ts
  routes/
    index.ts
  services/
    example.ts
  frontend/
    pages/
      index.tsx
      layout.tsx
      _document.html
      error/
        default.tsx
    components/
      AppShell.tsx
    styles/
      index.css
    locales/
      en-US.ts
public/
  vext-mark.svg
  favicon.svg

The important boundary is physical:

• src/routes/** and src/services/** run on the server.
• src/frontend/pages/** and src/frontend/components/** are UI sources used by SSR and browser builds according to render mode; a page file alone does not register a URL.
• Do not import services, database clients, secrets, or Node-only modules from frontend files.
• public/** holds fixed-path files copied into the frontend build and recorded in the deploy manifest; recording them does not upload them to a CDN.
• Add src/frontend/assets/**, other languages, and business pages as needed; they are not already in the default starter.

#First Page

In a newly created full-stack app, replace both the home page and its route with the complete examples below. Replacing the whole original route removes its starter API handlers; retain them if needed. No additional business service is required.

// src/frontend/pages/index.tsx
export default function HomePage(props: { greeting: string }) {
  return <main>{props.greeting}</main>;
}

Render it from a route:

// src/routes/index.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get("/", {}, (_req, res) => {
    res.render("index", { greeting: "Hello from Vext" });
  });
});

Visit / and expect Hello from Vext in the HTML. If the response is HTML without that text, inspect terminal errors, frontend enablement, and the page ID. See Getting Started for a complete walkthrough.

res.render(page, props?, options?) has three arguments:

#Current Capabilities

These features have separate conditions. React 19 or the default starter alone does not imply that every feature is enabled:

See Boundaries and Roadmap for details. Browser assets and server output must come from matching builds. Deploying static files does not replace the Vext server process.

#Reading Paths

Use the left navigation as the main map. It is intentionally split into concept, task, and reference layers.

The Frontend integration page connects the backend guide to this section and retains older links.