docs: links links links

CONTRIBUTING.md

@@ -2,6 +2,14 @@
 
 domco is open to contributions and is licensed under the MIT license. If you find a bug or have an idea feel free to create an issue to get feedback before going to the work of creating a PR.
 
+## dependencies
+
+domco currently has no dependencies other than Vite, please take this into consideration when contributing.
+
+## scope
+
+The scope of the project is to be a minimal wrapper to add server-side functionality to Vite. Some of the things that are outside the scope include adding a server framework, or a UI library into the core.
+
 ## clone
 
 - Clone the monorepo and run `npm i` to install dependencies.

apps/docs/package.json

@@ -14,6 +14,6 @@
 		"domco": "*",
 		"drab": "^5.4.2",
 		"tailwindcss": "^3.4.12",
-		"uico": "^0.3.1"
+		"uico": "^0.3.2"
 	}
 }

apps/docs/src/client/tailwind.css

@@ -148,18 +148,5 @@
 				padding-inline-start: 0;
 			}
 		}
-
-		section {
-			&:first-of-type {
-				margin-block-start: 0;
-			}
-		}
-
-		li {
-			padding-block-start: theme(padding.2);
-			:last-of-type {
-				padding-block-end: theme(padding.1);
-			}
-		}
 	}
 }

apps/docs/src/server/content/_preview.md

@@ -25,10 +25,14 @@ Server-side JavaScript runtimes are standardizing on the Web [`Request`](https:/
 
 One of the main goals of domco is to be able to create full-stack applications using vanilla JavaScript. With domco, it's easy to achieve the same developer experience as other frameworks that are based around a UI library, without having to pull in additional dependencies. By default, domco only bundles only the code you write, making it efficient and straightforward.
 
-If you need a UI framework, you can still use any Vite plugin as you would in a traditional Vite application.
+If you need a UI framework, you can still use any [Vite plugin](https://vitejs.dev/plugins/) as you would in a traditional Vite application. These plugins will also work on the server side.
 
 domco is compatible with any server-side JavaScript framework that provides a web request handler taking a `Request` argument and returning a `Response`. Check out the [examples](/examples) to see how to use popular server frameworks with domco.
 
 ### Minimal Dependencies
 
 domco is lightweight, relying solely on Vite as its dependency. This results in quick installation times, fast build and development processes, and a reduced risk of supply chain attacks.
+
+### Open Source
+
+domco is open source under the [MIT License](https://github.com/rossrobino/domco/blob/main/LICENSE.md). Contributions are welcome, see the [contributing guide](https://github.com/rossrobino/domco/blob/main/CONTRIBUTING.md) for instructions.

apps/docs/src/server/content/deploy.md

@@ -1,6 +1,6 @@
 # Deploy
 
-Run `vite build` to build your application into `dist/`.
+Run [`vite build`](https://vitejs.dev/guide/cli.html#vite-build) to build your application into `dist/`.
 
 ```
 .
@@ -27,6 +27,8 @@ Check out the [deployment examples](/examples#deployment) to see how to do this.
 
 Add a deployment adapter within your Vite config to output your app to a different target with no additional configuration.
 
+### Example
+
 ```ts {4,11-13}
 // vite.config
 import { domco } from "domco";
@@ -73,3 +75,17 @@ The [Vercel](https://vercel.com) adapter outputs your app to the [Build Output A
 - Supports on demand [Image Optimization](https://vercel.com/docs/image-optimization) when configured in the adapter config. Set the `src` attribute of an image using the `/_vercel/image/...` [optimized URL format](https://vercel.com/docs/image-optimization#optimized-url-format). In `dev` and `preview` modes, domco will redirect to the original image.
 
 ![A screenshot of the Vercel Build and Development Settings UI. Set the Framework Preset field to "Other" and leave all of the other options blank.](/_vercel/image?url=/images/vercel/build-settings.png&w=1280&q=100)
+
+### Creating an adapter
+
+If you'd like to deploy a domco app to a different provider, and you need many configuration steps for this to take place you can create an adapter.
+
+Check out the [current adapters](https://github.com/rossrobino/domco/tree/main/packages/domco/src/adapter) to see how to make your own.
+
+Adapters take care of these deployment steps.
+
+1. Set [`ssr`](https://vitejs.dev/config/ssr-options.html) options if changes are needed, for example if you are deploying to an edge function, set this to `"web worker"`.
+2. Create an entry point for the target environment by using the `handler` from `dist/server/app.js`. This could be reexporting it as a different export, or applying to a node server.
+3. Within the entry point, serve the `dist/client/*` directory as static assets, and the `dist/client/_immutable/*` directory with immutable cache headers. Static assets must be hit before the `handler` to take advantage of prerendering. When an asset is not found, the request needs to fallthrough to the `handler`.
+
+If you think others might benefit from your adapter you can [create an issue](https://github.com/rossrobino/domco/issues) or pull request to propose a new adapter. Adapters should be created for zero configuration deployments for deployment providers, not specific to JavaScript runtimes.

apps/docs/src/server/content/examples.md

@@ -101,7 +101,7 @@ export const handler: Handler = async (req) => {
 
 ### Node server
 
-Here's an example of how to serve your app using the result of your build using `node:http` and [`sirv`](https://github.com/lukeed/sirv/tree/master/packages/sirv).
+Here's an example of how to serve your app using the result of your build using `node:http`, [`sirv`](https://github.com/lukeed/sirv/tree/master/packages/sirv), and [`domco/listener`](https://github.com/rossrobino/domco/blob/main/packages/domco/src/listener/index.ts).
 
 ```ts
 // server.js

apps/docs/src/server/content/tutorial.md

@@ -1,10 +1,10 @@
 # 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](https://vitejs.dev/) documentation for more information and configuration options.
+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](https://vitejs.dev/) for more information and configuration options.
 
 ## Create a new project
 
-To get started, you'll need to have [Node](https://nodejs.org) (recommended), [Bun](https://bun.sh/), or [Deno](https://deno.com) (experimental support) or installed on your computer. Then run the `create-domco` script to create a new project. If you already have an existing client-side Vite project check out the [migration instructions](/migrate).
+To get started, you'll need to have [Node](https://nodejs.org) (recommended), [Bun](https://bun.sh/), or [Deno](https://deno.com) (experimental support) or installed on your computer. Then run the [`create-domco`](https://github.com/rossrobino/domco/tree/main/packages/create-domco) script to create a new project. If you already have an existing client-side Vite project check out the [migration instructions](/migrate).
 
 ### Node
 
@@ -39,7 +39,7 @@ The `app` entry point is located in within `src/server/`, this is the server ent
 		└── +app.(js,ts,jsx,tsx)
 ```
 
-`+app` modules export a `handler` function that takes in a `Request`, and returns a `Response`.
+`+app` modules export a `handler` function that takes in a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
 
 ```ts
 // src/server/+app.ts
@@ -48,7 +48,7 @@ export const handler = async (req: Request) => {
 };
 ```
 
-From here, it's up to you. For example, you could route different requests to different responses, based on the `req.url`.
+From here, it's up to you. For example, you could route different requests to different responses, based on the [`req.url`](https://developer.mozilla.org/en-US/docs/Web/API/Request/url).
 
 ```ts
 // src/server/+app.ts
@@ -65,13 +65,13 @@ export const handler = async (req: Request) => {
 };
 ```
 
-Or add a framework like [Hono](/examples#hono) to do your routing and more.
+Or [add a framework](/examples#server-frameworks) like [Hono](/examples#hono) to do your routing and more.
 
 ### +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`](#client%3Apage) virtual module.
+domco [configures Vite](https://vitejs.dev/guide/build#multi-page-app) 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`](#client%3Apage) virtual module.
 
 ```txt {4}
 .
@@ -84,7 +84,7 @@ domco configures Vite to process each `+page.html` as a separate entry point aut
 
 ### +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 in pages via a `script` tag, or on the server _without_ a page by using the [`client:script`](#client%3Ascript) virtual module.
+Each `+script.(js,ts,jsx,tsx)` file within `src/client/` will be [processed as an entry point](https://rollupjs.org/configuration-options/#input) by Vite. Client-side scripts can be used in pages via a `script` tag, or on the server _without_ a page by using the [`client:script`](#client%3Ascript) virtual module.
 
 ```txt {4}
 .
@@ -97,11 +97,13 @@ Each `+script.(js,ts,jsx,tsx)` file within `src/client/` will be processed as an
 
 ## Virtual Modules
 
-domco provides a doorway to the client via virtual modules. These allow you to not have to worry about getting the hashed filenames for client assets after the build is complete. You can easily serve a `+page` or include the tags for a `+script` in a response.
+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](https://vitejs.dev/guide/api-plugin.html#virtual-modules-convention). You can easily serve a `+page` or include the tags for a `+script` 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.
+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`](https://vitejs.dev/guide/api-plugin.html#transformindexhtml) hook on the imported page and inlines it into your server build.
 
 ```ts {2,8}
 // returns transformed content of `src/client/+page.html`
@@ -123,7 +125,7 @@ export const handler = async (req: Request) => {
 
 You can also easily get the `<script>` tags for any `+script` module on the server as well. These script tags (including all imports) can be accessed via 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.
+In development, domco links the scripts to the source. In production, domco [reads](https://vitejs.dev/guide/backend-integration.html) the [manifest](https://vitejs.dev/config/build-options.html#build-manifest) generated by the client build and includes the hashed version of these file names and their imports.
 
 ```ts {2,13}
 // returns transformed content of `src/client/+script.ts`

apps/tester/package.json

@@ -16,6 +16,6 @@
 		"domco": "*",
 		"react": "^18.3.1",
 		"react-dom": "^18.3.1",
-		"uico": "^0.3.1"
+		"uico": "^0.3.2"
 	}
 }