Getting Started

Build Your First Site

This guide connects the main Curvea pieces into one small project. It assumes you already know HTML, CSS, JavaScript, and npm.

1. Create the project

curvea new my-site
cd my-site
npm install

Choose the Basic website template if you want the starter Document, layout, page, CSS, and JavaScript files created for you.

2. Define the document shell

src/Document.csc owns the outer HTML document:

@document

<!DOCTYPE html>
<html lang="{{ site.language }}">
  <head>
    {{ head }}
  </head>
  <body>
    {{ app }}
  </body>
</html>

{{ head }} receives generated head content. {{ app }} receives the rendered page and layout.

3. Create a layout

src/layouts/Main.csc:

@layout Main(title)

<header>
  <a href="/">{{ site.name }}</a>
</header>

<main>
  {{ slot }}
</main>

<footer>© {{ CurrentYear }} {{ site.name }}</footer>

4. Create a component

src/components/Hero.csc:

@component Hero(title, description)

<section class="hero">
  <h1>{{ title }}</h1>
  <p>{{ description }}</p>
  {{ slot }}
</section>

5. Create the home page

src/pages/Home.csc:

@page
@use Main(title=page.title)
@import Hero

<Hero title="{{ page.title }}" description="{{ page.description }}">
  <a href="/about">About us</a>
</Hero>

Home.csc maps to /.

6. Add page data

src/data/pages/home.json:

{
  "title": "My Site",
  "description": "Built with Curvea."
}

Curvea merges this matching JSON into the page object, so the page can read page.title and page.description.

Create another page such as src/pages/About.csc and matching src/data/pages/about.json to add /about.

7. Add CSS

Put project CSS in src/assets/css/app.css:

.hero {
  max-width: 60rem;
  margin: 0 auto;
  padding: 5rem 1.5rem;
}

Curvea emits the CSS under dist/assets/css/ and links the main app.css entry when present.

8. Add JavaScript

Use src/assets/js/app.js for normal browser behavior:

document.documentElement.classList.add("js")

The main app.js entry is emitted as a module and included in the rendered site when present.

9. Run development

npm run dev

Open the local URL printed by the CLI and continue editing source files with live reload.

10. Build production output

npm run build

The production site is generated in:

dist/

For CI or static hosting, install from the lockfile with npm ci, run npm run build, and publish dist.

Where to go next

Use the reference sections for dynamic [slug] routes, @load, Markdown collections, pagination, built-in helpers, SEO, sitemap generation, and base-path deployments.

2 min read