Step 4 of 12 33% complete

Step 4: Routing with OpenAPI

What You'll Learn

Define routes using OpenAPI YAML syntax
Use x-view for frontend page routes
Use x-controller for API endpoints with operationId
Navigate between pages using anchor links
Understand how Forge handles client-side navigation

What You'll Build

Routes for both frontend pages and API endpoints.

Project Files Overview

NoEgo uses OpenAPI YAML files to define all routes. Click on files in the tree to explore. Files marked with NEW are the ones you'll create.

my-noego-app

ui/openapi/pages.yaml NEW

server

controller

openapi

api

pages

home

# Frontend page routes
modules:
  public:
    basePath: /
    x-layout:
      - layout/public_layout.svelte
    paths:
      /:
        get:
          summary: Home Page
          x-view: pages/home/main.svelte
      /about:
        get:
          summary: About Page
          x-view: pages/about/main.svelte
      /contact:
        get:
          summary: Contact Page
          x-view: pages/contact/main.svelte

Understanding the Route Structure

`x-view` - Frontend Page Routes

The x-view extension tells NoEgo to render a Svelte component for this route. When a user visits the URL, the component is rendered server-side and sent to the browser.

x-view: Path to the Svelte component (relative to ui/)
x-layout: Optional array of layout components to wrap the page

`x-controller` - API Endpoint Routes

For API endpoints that return JSON data, use x-controller with an operationId. The operationId maps directly to a method on your controller class.

x-controller: Path to the controller file (relative to server/)
operationId: Must match the method name on the controller exactly

`stitch.yaml` - Combining Route Files

The x-stitch array in your stitch.yaml combines multiple OpenAPI files into a single routing configuration. This keeps your routes organized and modular.

Navigation Between Pages

Forge automatically intercepts clicks on <a> tags and handles them as client-side navigation. This means you get SPA-like behavior without any special components or JavaScript.

How SPA Navigation Works

Forge intercepts the click event on internal links
It fetches the new page content via an internal request
The page content is swapped without a full reload
The browser URL is updated using the History API

This gives you fast, seamless navigation while still supporting server-side rendering and progressive enhancement.

What's Next?

Now that you understand routing, let's set up a database to persist our data. We'll configure SQLite and create migrations using the Proper CLI.

Troubleshooting

Previous Step All Steps Next Step