Tutorial
The following documentation covers the basics of creating a site and all of the features domco provides in addition to Vite. See the Vite documentation for more information and configuration options.
Create a new project
To get started, you’ll need to have Node or Bun installed on your computer. Then run the create script below to create a new project. If you already have an existing client-side Vite project you would like to add a server to, check out the examples repository.
npm create domco@latest
Entry points
domco identifies the entry points of your application by file name. These entry points are prefixed with + so they are easily identifiable.
+app
The application entry point is located in within src/server/, this is the server entry point for your application.
src/
└── server/
└── +app.(js,ts,jsx,tsx)
The +app module exports a default object with a fetch function that takes in a Request, and returns a Response.
// src/server/+app
export default {
fetch(req: Request) {
return new Response("Hello world");
},
};
From here, you could route different requests to different responses, based on the req.url.
// src/server/+app
export default {
fetch(req: Request) {
const url = new URL(req.url);
if (url.pathname === "/") {
return new Response("Hello");
} else if (url.pathname === "/world") {
return new Response("World");
}
return new Response("Not found", { status: 404 });
},
};
Alternatively, you can use a Fetch API compatible router like Hono. Most routers provide a fetch or handler method to handle requests in production, which you can pass into the default export.
// src/server/+app
import { Hono } from "hono";
const app = new Hono();
// pass to the default export
export default { fetch: app.fetch };
// or if the method is named `fetch`, export directly
export default app;
Client IP
domco passes connection information to fetch as the second argument. info.ip is the client’s IP address, which you can use for rate limits or logs.
// src/server/+app
import type { FetchInfo } from "domco";
export default {
fetch(req: Request, info?: FetchInfo) {
return new Response(`Your IP is ${info?.ip}`);
},
};
domco never reads info.ip from a header the client can set. The dev and preview servers pass the socket’s address, and each adapter passes the client IP its platform verifies. If you are using a router like ovr, pass app.fetch directly and it receives info as its options.
+page
To create a page, add +page.html file in a directory within src/client/.
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. You can serve the transformed contents of a page via the client:page virtual module.
src/
├── client/
│ └── +page.html
└── server/
└── +app.ts
+script
Each +script.(js,ts,jsx,tsx) file within src/client/ will be processed as an entry point by Vite. Client-side scripts can be used on the server without a page by using the client:script virtual module.
src/
├── client/
│ └── +script.ts
└── server/
└── +app.ts
+style
Each +style.css file within src/client/ also becomes an entry point. Styles can be accessed on the server using the client:style virtual module.
src/
├── client/
│ └── +style.css
└── server/
└── +app.ts
Virtual modules
One challenging aspect of full-stack development and server-side rendering is managing the client files correctly during development and production. In development, you need to link directly to source files to benefit from features like TypeScript support and Hot Module Replacement (HMR). In production, the build process transforms each file and applies a hash to the filename for caching purposes.
domco takes care of these problems using virtual modules. You can easily serve a +page or include the tags for a +script or +style in a response. domco ensures the correct assets are linked during development and in production.
client:page
You can import the transformed HTML of any +page.html from this module or one of it’s sub-paths. domco calls Vite’s transformIndexHtml hook on the imported page and inlines it into your server bundle.
// src/server/+app
// `html` is transformed content of `src/client/+page.html`
import { html } from "client:page";
// `src/client/other/+page.html`
import * as other from "client:page/other";
export default {
fetch(req: Request) {
return new Response(
html, // bundled client application
{ headers: { "content-type": "text/html" } },
);
},
};
You can also import the chunk information for the linked JS entry point to a page. This holds the same data client:script provides.
import { chunk } from "client:page";
chunk.src.assets; // ex: assets might contain a font path you want to preload
client:script
Easily get the <script> and related <link> tags for any +script module on the server by accessing the client:script virtual module. They can be included in an HTML string, or inside of JSX.
In development, domco links the scripts to the source. In production, domco reads the manifest generated by the client build and includes the hashed version of these file names and their imports.
// src/server/+app
import {
// arrays of the hashed related paths for the entry point.
src,
// string of <script> and <link> tags for related resources
tags,
} from "client:script";
export default {
fetch(req: Request) {
return new Response(
`<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
${tags}
<title>Document</title>
</head>
...
</html>`,
{ headers: { "content-type": "text/html" } },
);
},
};
client:style
client:style holds the asset information for a +style.css entrypoint.
// /client/+style.css
import * as style from "client:style";
// /client/other/+style.css
import * as other from "client:style/other";
style.tags; // `<link rel="stylesheet" ... >
Prerender
Add a prerender property to the default export to prerender routes. prerender can be an Array or a Set of paths to prerender, or a function that returns the paths.
// src/server/+app
export default {
fetch(req) {
//...
},
prerender: ["/", "/post-1", "/post-2", "/some.css", "/some.json"],
};
After the Vite build is complete, domco will import default.fetch from your application and make a request to each default.prerender path provided. domco imports your +app module during every build to read prerender, even when it has nothing to prerender. Before importing it, domco loads every variable from your project’s .env files for the build’s mode into process.env, without overwriting variables that are already set. If your app checks environment variables as it loads, set them in the build environment or a .env file, or check them when the first request arrives. When the import fails, domco logs the error and the build continues without prerendering. The responses will be written to dist/client/(path) files upon build. If the path does not have an extension, /index.html will be added to the end of the file path.
For the export above, domco would request each path and generate the following files from the responses.
| Prerender Path | File Created |
|---|---|
/ |
dist/client/index.html |
/post-1 |
dist/client/post-1/index.html |
/post-2 |
dist/client/post-2/index.html |
/some.css |
dist/client/some.css |
/some.json |
dist/client/some.json |
If you are using an adapter, these static files will be served in front of your fetch handler. So when an index.html file is found for the route, it is served directly without hitting your fetch handler.
Local HTTPS
Browsers treat http://localhost as a secure context, but some features, browsers, and setups still need HTTPS during development, for example passkeys, cookies with Secure or the __Host- prefix sent from another device on your network, or a custom hostname. To serve the dev server over HTTPS without certificate warnings, create a certificate your system trusts with mkcert.
# add mkcert's local certificate authority to the system and browser trust stores, once per machine
mkcert -install
# create a certificate for localhost in the project
mkcert -cert-file .cert/localhost.pem -key-file .cert/localhost-key.pem localhost 127.0.0.1 ::1
Then pass the files to server.https in your Vite config. vite preview uses the same setting.
// vite.config.ts
import { domco } from "domco";
import fs from "node:fs";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [domco()],
server: {
https: {
cert: fs.readFileSync(".cert/localhost.pem"),
key: fs.readFileSync(".cert/localhost-key.pem"),
},
},
});
Run vite and open https://localhost:5173. Add .cert/ to .gitignore. The certificate is only trusted on machines that ran mkcert -install, and the key in $(mkcert -CAROOT) can sign certificates for any site, so never share it. To use a hostname such as app.localhost or your machine’s network address, list it when creating the certificate. To open the site on another device, install mkcert’s rootCA.pem on that device too.
With HTTPS enabled, Vite serves the dev server over HTTP/2 and req.url starts with https://. Plugins such as @vitejs/plugin-basic-ssl create a certificate the system doesn’t trust, so browsers show a warning first.
That’s it!
domco has a minimal API surface area and tries to get out of your way during development. For more examples (framework, library) check out the domco-examples repository.
Next, learn how to deploy your application.