Added template transform api and changed documentation

[pixelmund]

Before submitting the PR, please make sure you do the following

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

I couldn't find any issue or milestone about transforming the app.html template as requested in #1642 and 1695.

This opens up for stuff like adding classes to the html element or changing the language attribute.
It would be really useful for tailwind darkmode or theming in general, adding csrf token on a meta tag etc.

Im open for any changes to this, its also okay if you don't consider this right now it would just help me adding proper darkmode to my project without setting it on the client with javascript.

Tests

• Run the tests with pnpm test and lint the project with pnpm lint

I don't really know how to write tests for this atm.

Changesets

• If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpx changeset and following the prompts

[benmccann]

This seems fairly reasonable to me. My only suggestion is that it'd be nice to have a test

[pixelmund]

I have added a basic test, but seems like i did something wrong.
Will have to investigate later.

It works locally..

[benmccann]

looks like it was just a flaky test. I kicked the tests off again and they're all passing now

[Rich-Harris]

Thanks for the PR. Over on #334 (comment) we've been discussing making it easier to add custom logic to the main request handler, in such a way that you could do this:

// src/hooks.js
import cookie from 'cookie';

export function getContext({ headers }) {
  return {
    dark: cookie.parse(headers.cookie).dark === 'true'
  }
}

export function handle(request, render) {
  const rendered = render(request); // { status, headers, body }

  if (rendered.headers['content-type'] === 'text/html') {
    return {
      ...rendered,
      body: rendered.body.replace('%My.HtmlClass%', request.context.dark ? 'dark' : 'light')
    };
  }

  return rendered;
}

This is slightly lower-level than transformTemplate and therefore not quite as concise, in the example of applying a dark mode class, but it also gives us more power because we can augment the body as well as the shell (potentially useful for A/B testing etc?).

What do you think?

[benmccann]

I think the API in #334 (comment) should cover all the use cases this would cover. Perhaps to future-proof it, the API should be handle({request, render}). Then we might also be able to extend it to handle({request, render, isPage}) or something like that to make it slightly more concise to tell if it's a page vs endpoint

[pixelmund]

Thanks for the PR. Over on #334 (comment) we've been discussing making it easier to add custom logic to the main request handler, in such a way that you could do this:

// src/hooks.js
import cookie from 'cookie';

export function getContext({ headers }) {
  return {
    dark: cookie.parse(headers.cookie).dark === 'true'
  }
}

export function handle(request, render) {
  const rendered = render(request); // { status, headers, body }

  if (rendered.headers['content-type'] === 'text/html') {
    return {
      ...rendered,
      body: rendered.body.replace('%My.HtmlClass%', request.context.dark ? 'dark' : 'light')
    };
  }

  return rendered;
}

This is slightly lower-level than transformTemplate and therefore not quite as concise, in the example of applying a dark mode class, but it also gives us more power because we can augment the body as well as the shell (potentially useful for A/B testing etc?).

What do you think?

Sounds fairly reasonable to me, I like this approach even better.

[pixelmund]

Im closing this in favor of #670