---
title: 'Custom HTML shell'
slug: custom-html-shell
description: 'Replace the default HTML wrapper with a custom shell template containing Mochi placeholders.'
---
## Custom HTML shell
`htmlShell` overrides the default `` wrapper that Mochi renders pages into. Pass either a path to an `.html` file (detected by the `.html` suffix) or the template string directly:
```ts
// file: src/index.ts
import { Mochi } from 'mochi-framework';
await Mochi.serve({
htmlShell: './src/shell.html',
routes: {
'/': Mochi.page('./src/Home.svelte'),
},
});
```
The default shell lives at `packages/mochi/src/templates/default-shell.html` — copy it as a starting point.
### Placeholders
A custom shell must contain four placeholders. Each is replaced once per request by `Mochi.resolveHtmlShell()`:
| Placeholder | Replaced with |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| `{{mochi.head}}` | `` output plus the warning-collector bootstrap script. |
| `{{mochi.css}}` | Island-display rules, island-failure styles, and `` tags for compiled CSS. |
| `{{mochi.body}}` | Rendered component HTML, debug-info script, dev toolbar mount, dev error overlay, error-report script. |
| `{{mochi.script}}` | Hydration bootstrap `