Skip to main content

Project Structure

Coral follows a minimal and predictable project structure designed for fullstack applications built with React. The layout is intentionally simple to reduce cognitive overhead while supporting scalable routing, static asset handling, and backend logic via server functions or simple API routes.

This section describes the key directories and files in a typical Coral project created from the core/ folder.

Root Directory​

├── public/
├── src/
│   ├── components/
│   ├── routes/
│   ├── api.ts
│   ├── getPosts.ts
│   └── index.tsx
├── .gitignore
├── package.json
├── index.html
└── app.config.ts

public/​

Contains static assets (e.g., images, fonts, icons) that should be served as-is. Files placed here are exposed at the root of your site URL. For example, public/favicon.ico is available at /favicon.ico.

  • No build processing is applied to these files.
  • Ideal for static files that don't need bundling.

src/ — Source Code​

The main application logic lives inside the src/ directory.

src/routes/​

This directory holds the client-side route definitions. Coral uses TanStack Router with file-based routing, so each .tsx file under routes/ corresponds to a route.

Example:

src/
└── routes/
    ├── index.tsx          → `/`
    ├── about.tsx          → `/about`
    └── posts.tsx          → `/posts`

Route definitions are used by TanStack Router to generate the route tree.

When the development server is started, a file named routeTree.gen.ts is automatically created to represent this tree in code.

src/api.ts​

A central API handler file. This is Coral's current mechanism for handling server-side HTTP requests.

  • Supports route and method detection
  • Responds to requests like GET /api/posts with static or dynamic data
  • Will be replaced by file-based API routing in a future update

Example logic:

// GET /api/posts
if (method === 'GET' && path === '/posts') {
  return json([...]); // Return array of data
}

In future versions, the api.ts entrypoint will be replaced or supplemented by an api/ directory with file-based route handlers.

src/getPosts.ts​

Contains a simple server-side function that fetches data from an external API. It begins with the "use server" directive, marking it for server-only execution.

This separation helps isolate backend logic from route handlers and keeps the codebase modular and testable.

src/index.tsx​

This is the client-side entry point of the Coral application. It initializes the React application, sets up the router using TanStack Router, and renders the app into the DOM via createRoot.

Key responsibilities:

  • Bootstraps the React component tree
  • Configures and registers the route tree (routeTree.gen.ts)
  • Wraps the app in StrictMode to help surface potential issues in development
  • Renders the app into the #root element defined in index.html

The file also declares a module augmentation for TanStack Router to ensure type-safe router access throughout the app.

Generated Files​

.tanstack/​

Auto-generated by TanStack Router when the dev server runs. Contains intermediate build artifacts, such as:

  • Static routing metadata
  • Route tree generation files

This folder should be ignored by version control (.gitignore).

routeTree.gen.ts​

Also generated at runtime by the router plugin. It contains the statically analyzable route tree used internally by TanStack Router for type-safe navigation and optimizations.

Do not manually edit this file. It is regenerated automatically and is safe to exclude from commits.

Configuration Files​

app.config.ts​

Coral’s main application configuration file. Passed into Vinxi’s createApp() function, it sets up:

  • Routing behavior
  • Plugins (e.g., server functions, React SSR support)
  • Build and runtime configuration

This file defines the execution context for both server and client.

index.html​

Used by Vite and Vinxi to define the root HTML structure of the application. This file includes the mounting point (<div id="root">) and script tags for loading the client bundle.

Planned Additions​

Once SSG, SSR, and backend adapters are integrated, the following directories may be added:

api/             → File-based server routes
lib/             → Utility functions
test/            → Unit/e2e test suites

These will be documented as they are introduced.