Tutorial

Create a new project

To get started, you’ll need to have Node.js and npm installed on your computer.

Run this command in your terminal.

npm create domco@latest

This command creates files in your project’s directory instead of having to manually set up the plugin with Vite.

The following documentation covers the basics of creating a site and all of the features domco provides in addition to Vite and Hono. See the Vite or Hono documentation for more information and configuration options.

+page

Your project is located in src/—this serves as the root directory of your project. src/+page.html can be accessed at https://example.com, while src/nested/+page.html can be accessed at https://example.com/nested.

To create another page, add another +page.html file in another directory within src/.

domco configures Vite to process each +page.html as a separate entry point automatically. Everything linked in these pages will be bundled and included in the output upon running vite build.

.
└── src/
	├── +page.html
	└── nested/
		└── +page.html

Now you can navigate to /nested with an anchor tag.

<a href="/nested">Nested</a>

+client

Each +client.(js,ts,jsx,tsx) file within src/ will be processed as an entry point by Vite. Client-side scripts can be used in pages or on the server without a page.

domco will automatically inject a tag for any +client file that is located next to a +page.html into the page so you don’t need to link it.

.
└── src/
	├── +client.ts
	└── +page.html

If you would like to like to add another script, you can import it into +client, or add a script tag to your HTML page.

<!-- +page.html -->
<script type="module" src="/some-other-script.ts"></script>

Now that this script is included in an entry point +page.html, the script, and anything that is imported, will be bundled and included in the final build.

+server

Turn any path in src into a Hono app by adding a +server.(js,ts,jsx,tsx) file.

.
└── src/
	├── +page.html
	└── +server.ts

You have now converted this route path from a static page into a Hono application based at that path.

// src/+server.ts
import { Hono } from "hono";

const app = new Hono();

app.get("/", (c) => c.html("hello world"));

// you can also create another route from here
// this route can be accessed at https://example.com/another-route
app.get("/another-route", (c) => c.html("another route"));

export default app;

Page context

domco sets a page context variable for you that will return the transformed HTML of any +page.html requested.

app.get("/", (c) => {
	// ./+page.html
	const page = c.var.page();

	// src/nested/+page.html
	const anotherPage = c.var.page("/nested");

	return c.html(page);
};

Client context

You can also easily get the tags for any +client file on the server as well. These script tags (including all imports) can be accessed using the client context variable within your Hono application. They can be included in an HTML string, or inside of JSX.

app.get("/", (c) => {
	// gets `./+client.(js,ts,jsx,tsx)`
	const tags = c.var.client();

	// gets `src/route/path/+client.(js,ts,jsx,tsx)`
	const differentTags = c.var.client("/route/path");

	return c.html(html`
		${tags}
		<p>Partial with client side script</p>
	`);
});

domco reads the manifest generated by the client build and includes the hashed version of these file names in production.

Server context

domco also sets a server context variable to make it easier to request local routes (it’s just fetch with the origin set.)

// dev: fetch("http://localhost:5173/route/path")
// prod: fetch("https://example.com/route/path")
const res = await c.var.server("/route/path");

Prerender

Export a prerender variable to prerender pages.

// src/posts/+server.ts
import type { Prerender } from "domco";

// prerender current route
export const prerender: Prerender = true;

// prerender multiple paths relative to the current route.
export const prerender: Prerender = ["/", "/post-1", "/post-2"];

Route ordering

Routes are sorted and applied from most specific to least.

.
└── src/
	├── +server.ts - 3rd
	└── nested/
		├── +server.ts - 2nd
		└── another/
			└── +server.ts - 1st

So if you write a handler within src/nested/+server.ts to handle requests for "/", and also one inside src/+server.ts to handle "/nested", the handler within src/nested/+server.ts will be executed.

+setup

You can also create a src/+setup.(js,ts,jsx,tsx) file, this app will be added to your application before other routes. This is an escape hatch, for example if you need some middleware to apply to all routes in your application and you don’t want to import it into each +server module.

Styles

Styles can be linked to an HTML page using the link tag within the head tag, or by importing a stylesheet into a client side script.

Notice that the href for these links are relative to the root directory—this tag will link src/style.css.

<!-- +page.html -->
<head>
	<link rel="stylesheet" href="/style.css" />
</head>

// +client.js
import "/style.css";