Skip to main content
COSMOS RSC follows a clear separation between your application code and the framework’s core functionality.

​
Directory overview

A typical COSMOS RSC project has the following structure: 
my-cosmos-app/
├── app/                    # Your application code
│   ├── actions/           # Server actions
│   ├── components/        # React components
│   ├── pages/            # Page components
│   ├── globals.css       # Global styles
│   └── root-layout.js    # Root layout component
├── core/                  # Framework core (don't modify)
│   ├── build/            # Build system
│   ├── client/           # Client-side runtime
│   ├── server/           # Server-side runtime
│   └── rsc-html-stream/  # Streaming utilities
├── .cosmos-rsc/          # Build artifacts (generated)
│   ├── client.js         # Client bundle
│   ├── style.css         # Compiled CSS
│   └── *.map            # Source maps
└── package.json          # Project configuration

​
The app/ directory

This is where all your application code lives.

​
Pages

The app/pages/ directory contains your page components. Each file maps to a route: 
app/pages/
├── index.js              # / route
├── about.js              # /about route
└── features/
    ├── forms.js          # /features/forms route
    └── streaming.js      # /features/streaming route
Page components are React Server Components by default and can be async:
app/pages/index.js
export default async function HomePage() {
  const data = await fetchData();
  return <div>{data}</div>;
}

​
Components

The app/components/ directory holds reusable components. Components are Server Components unless marked with 'use client':
app/components/button.js
'use client';

export function Button({ children, onClick }) {
  return <button onClick={onClick}>{children}</button>;
}

​
Actions

The app/actions/ directory contains server actions - functions that run on the server and can be called from forms or client components:
app/actions/form-actions.js
'use server';

export async function submitForm(formData) {
  // Handle form submission
}

​
Root layout

The app/root-layout.js file defines the HTML structure that wraps all pages:
app/root-layout.js
export default function RootLayout({ children }) {
  return (
    <html lang='en'>
      <head>
        <meta charSet='utf-8' />
        <meta name='viewport' content='width=device-width, initial-scale=1' />
        <title>My App</title>
        <link rel='stylesheet' href='/style.css' />
      </head>
      <body>{children}</body>
    </html>
  );
}

​
Global styles

The app/globals.css file contains your global CSS, including Tailwind imports:
app/globals.css
@import 'tailwindcss';

/* Your custom styles */

​
The core/ directory

The core/ directory contains the framework implementation. You typically don’t need to modify these files.

​
Build system

  • core/build/index.js - Build orchestration
  • core/build/webpack.config.js - Webpack configuration for client bundle

​
Client runtime

  • core/client/index.js - Client entry point
  • core/client/components/ - Internal client components
  • core/client/lib/ - Client-side utilities (routing, RSC payload handling)

​
Server runtime

  • core/server/index.js - Express server
  • core/server/lib/ - Server utilities (cookies, manifests, rendering)
  • core/server/exports.js - Public server APIs

​
Build artifacts

When you run npm run build, COSMOS RSC generates the .cosmos-rsc/ directory:
  • client.js - Bundled client-side JavaScript
  • style.css - Compiled CSS with Tailwind
  • *.map - Source maps for debugging
These files are served by the development server and should be deployed with your application.

​
Package configuration

The package.json includes important configuration: 
{
  "imports": {
    "#cosmos-rsc/server": "./core/server/exports.js"
  },
  "scripts": {
    "build": "node core/build/index.js",
    "server": "node --conditions react-server core/server/index.js",
    "start": "npm run build && npm run server"
  }
}
The imports field creates the #cosmos-rsc/server alias for importing server utilities like cookies().

Build docs developers (and LLMs) love

Get started for freeTalk to us