Private Folders

A folder under app/ whose name starts with an underscore is never routed, so components and helpers can live next to the routes that use them.

app/
  blog/
    _components/
      PostCard.tsx      # imported by blog/page.tsx, never a URL
      page.tsx          # ignored: no /blog/_components route
    _lib/
      format-date.ts
    page.tsx            # /blog

Reference

Convention

Any folder whose name begins with _, at any depth: _components, _lib, _utils.

Behavior

• Route discovery skips the folder and everything below it. Nothing inside becomes a page, a route.ts handler, a layout, or a loading, error or not-found file, even if it has one of those names.
• Its modules work like any other module: pages, layouts and route handlers import them normally.
• gio routes and .gio/routes.d.ts leave them out.

Examples

Colocate a component

import React from 'react';
import { GioLink } from '@gio.js/react';

export function PostCard({ slug, title }: { slug: string; title: string }) {
  return (
    <GioLink href={`/blog/${slug}`} className="post-card">
      {title}
    </GioLink>
  );
}

import React from 'react';
import { PostCard } from './_components/PostCard';

const POSTS = [
  { slug: 'hello-world', title: 'Hello, world' },
  { slug: 'routing', title: 'How routing works' },
];

export default function Blog() {
  return (
    <ul>
      {POSTS.map((post) => (
        <li key={post.slug}>
          <PostCard {...post} />
        </li>
      ))}
    </ul>
  );
}

Good to know

• A folder is enough to keep a file out of routing only for the special names: a Button.tsx next to a page.tsx is never a route anyway. Private folders are for grouping, and for keeping a file named page.tsx or route.ts from being routed.
• No URL segment can start with _ through a folder name. When you need one, answer it with a rewrite to a route without the underscore.
• The rule also keeps app routes out of /_gio, which the server reserves for its own endpoints.
• Plain .css files in a private folder are still served by their path (app/_styles/x.css at /_styles/x.css) unless [css] enabled = false. See CSS files.
• Files in private folders are part of app/, so in development editing them restarts the worker like any other change there.

Related

• Layouts & Pages: Private folders
• Route Groups, Project Structure

Version history