# @sveltekit-addons/document

> A tiny utility for SvelteKit that lets you change the ``, ``, and `` tags from any page or layout—with full SSR support. Here's an example:

Latest version **1.0.1** (published 2023-07-22) · 0 weekly downloads

## Install

```sh
npm install @sveltekit-addons/document
pnpm add @sveltekit-addons/document
yarn add @sveltekit-addons/document
bun add @sveltekit-addons/document
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2023-07-22 |
| First published | 2023-02-22 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 13.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | barvian |

## Links

- npm: https://www.npmjs.com/package/@sveltekit-addons/document
- npm.io page: https://npm.io/package/@sveltekit-addons/document

## Dependencies (3)

- [cheerio](https://npm.io/package/cheerio.md) ^1.0.0-rc.12
- [magic-string](https://npm.io/package/magic-string.md) ^0.29.0
- [svelte-parse-markup](https://npm.io/package/svelte-parse-markup.md) ^0.1.2

## Recent versions

- 1.0.1 (latest) — 2023-07-22
- 1.0.0 — 2023-02-24
- 0.0.1 — 2023-02-22

## README

# The missing document manager for SvelteKit

A tiny utility for SvelteKit that lets you change the `<html>`, `<head>`, and `<body>` tags from any page or layout—with full SSR support. Here's an example:

```svelte
<!-- you could already do this: -->
<svelte:head>
    <title>Hello world!</title>
</svelte:head>
<svelte:body on:click={onBodyClick} />

<!-- but now you can do this: -->
<ska:html lang="en" on:keyup={onHtmlKeyup} />
<svelte:body class:dark={darkModeEnabled} />
```

The full list of features it offers is:

- Expands `<svelte:body>` to work with attributes, not just event listeners (accessible in SSR via `%ska.body.attributes%` in `app.html`), which addresses this [long-standing feature request](https://github.com/sveltejs/svelte/issues/3105)
- Adds `<ska:html>` (ska = SvelteKit Addons), which forwards attributes and event listeners to the `<html>` element (accessible in SSR via `%ska.html.attributes%` in `app.html`)

## Installation

1. Grab the package from NPM:

   ```sh
   npm install @sveltekit-addons/document --save-dev
   ```

1. Include the preprocessor in your `svelte.config.js` file:

   ```diff
   + import { preprocessor as documentPreprocessor } from '@sveltekit-addons/document'

   export default {
   -   preprocess: [vitePreprocess()]
   +   preprocess: [vitePreprocess(), documentPreprocessor()] // Make sure it's at the very end
   }
   ```

1. Add the handle to your `src/hooks.server.js` (create that file if it doesn't exist):

   - If you don't have any other handles:
     ```diff
     + export { handle } from '@sveltekit-addons/document/hooks'
     ```
   - If you have a `handle` export already:

     ```diff
     + import { handle as documentHandle } from '@sveltekit-addons/document/hooks'
     + import { sequence } from '@sveltejs/kit/hooks'

     - export const handle = ...
     + const handle = ...
     + export const handle = sequence(handle, documentHandle)
     ```

1. Add the SSR placeholders to your `src/app.html`:

   - Manually:
     ```diff
     <!DOCTYPE html>
     - <html>
     + <html %ska.html.attributes%>
     <head>
         ...
     </head>
     - <body>
     + <body %ska.body.attributes%>
     ```
   - Or by using the provided `app.html` template (meaning you can delete yours):

     ```diff
     // svelte.config.js
     + import { appTemplate } from '@sveltekit-addons/document'

     export default {
         // ...
     +   kit: {
     +     files: {
     +       appTemplate
     +     }
     +   }
     }
     ```

## Gotchas

- `<ska:html>`'s event listeners don't get automatic types. Event listeners on the `<html>` element are pretty rare, though, and most of the time `<svelte:window>` could/should be used instead.

# Todo

- [ ] Handle CSP
- [ ] Allow adding elements portal-style to body

---
_Source: https://npm.io/package/@sveltekit-addons/document · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._