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";