feat: Solid.js support (#500)

* feat: @unhead/solid

* feat: Solid.js support

Author: harlan-zw

README.md

@@ -37,4 +37,3 @@ Visit the [documentation site](https://unhead.unjs.io/) for guides and API refer
 ## License
 
 MIT License © 2022-PRESENT [Harlan Wilton](https://github.com/harlan-zw)
-

docs/0.solid-js/1.installation.md

@@ -0,0 +1,195 @@
+---
+title: Installing Unhead with Solid.js
+description: Learn how to start using Unhead with Solid.js.
+navigation:
+  title: 'Installation'
+---
+
+## Introduction
+
+Unhead has first-class support for Solid.js, allowing you to manage your head tags using the `useHead()`{lang="ts"} hook, and other ecosystem hooks.
+
+It can directly replace [`Solid-Meta`](https://docs.solidjs.com/solid-meta), handling a more diverse set of use cases from SEO to structured data.
+
+It's designed to work with any Solid.js setup, however this guide assumes you're following a similar structure to the [Vite: ssr-solid-js-ts](https://github.com/bluwy/create-vite-extra/tree/master/template-ssr-solid-js-ts) template
+or a similar SPA setup.
+
+### Demos
+
+- [StackBlitz - Unhead - Vite + Solid.js SSR](https://stackblitz.com/edit/github-5hqsxyid)
+- [StackBlitz - Unhead - Solid.js SPA](https://stackblitz.com/edit/vitejs-vite-ggqxj5nx)
+
+## Setup
+
+### 1. Add Dependency
+
+Install `@unhead/solid-js`{lang="bash"} dependency to your project. The `next` tag is for v2 of Unhead which is required for Solid.js.
+
+:ModuleInstall{name="@unhead/solid-js@next"}
+
+### 2. Setup Client-Side Rendering
+
+To begin with, we'll import the function to initialize Unhead in our _client_ Solid.js app from `@unhead/solid-js/client`{lang="bash"}.
+
+In Vite this entry file is typically named `entry-client.ts`{lang="bash"}. If you're not server-side rendering, you can add this to your main Solid.js app entry instead.
+
+```tsx {1,7,12,14} [src/entry-client.ts]
+import { createHead, UnheadContext } from '@unhead/solid-js/client'
+import { hydrate } from 'solid-js/web'
+import App from './App'
+/* @refresh reload */
+import './index.css'
+
+hydrate(() => {
+  const head = createHead()
+  return (<UnheadContext.Provider value={head}><App /></UnheadContext.Provider>)
+}, document.getElementById('root'))
+```
+
+### 3. Setup Server-Side Rendering
+
+::note
+Serving your app as an SPA? You can [skip](/docs/solid-js/installation#_4-your-first-tags) this step.
+::
+
+Setting up server-side rendering is more complicated as it requires rendering out the tags to the HTML string before sending it to the client.
+
+We'll start with setting up the plugin in the _server_ entry this time. Make sure to import from `@unhead/solid-js/server`{lang="bash"} instead
+and add the `head` in the return object.
+
+```tsx {1,7,10,12,15} [src/entry-server.ts]
+import { createHead, UnheadContext } from '@unhead/solid-js/server'
+import { renderToString } from 'solid-js/web'
+import App from './App'
+
+export function render(_url: string) {
+  const unhead = createHead()
+  const html = renderToString(() => <UnheadContext.Provider value={unhead}><App /></UnheadContext.Provider>)
+  return { html, unhead }
+}
+```
+
+Now we need to render out the head tags _after_ Solid.js has rendered the app.
+
+Within your `server.js` file or wherever you're handling the template logic, you need to transform the template data
+for the head tags using `transformHtmlTemplate()`{lang="ts"}.
+
+```ts {1,9-14} [server.ts]
+import { transformHtmlTemplate } from '@unhead/solid-js/server'
+// ...
+
+// Serve HTML
+app.use('*all', async (req, res) => {
+  try {
+    // ...
+
+    const rendered = await render(url)
+
+    const html = await transformHtmlTemplate(
+      rendered.unhead,
+      template
+        .replace(`<!--app-head-->`, generateHydrationScript())
+        .replace(`<!--app-html-->`, rendered.html ?? '')
+    )
+
+    res.status(200).set({ 'Content-Type': 'text/html' }).send(html)
+  }
+  catch (e) {
+    // ...
+  }
+})
+// ..
+```
+
+### 4. Your First Tags
+
+Done! Your app should now be rendering head tags on the server and client.
+
+To improve your apps stability, Unhead will now insert important default tags for you.
+
+- `<meta charset="utf-8">`
+- `<meta name="viewport" content="width=device-width, initial-scale=1">`
+- `<html lang="en">`
+
+You may need to change these for your app requirements, for example you may want to change the default language. Adding
+tags in your server entry means you won't add any weight to your client bundle.
+
+```tsx {2,6-8} [src/entry-server.ts]
+import { createHead, UnheadContext } from '@unhead/solid-js/server'
+import { renderToString } from 'solid-js/web'
+import App from './App'
+
+export function render(_url: string) {
+  const unhead = createHead({
+    // change default initial lang
+    init: [
+      {
+        htmlAttrs: { lang: 'en' },
+        title: 'Default title',
+        titleTemplate: '%s - My Site',
+      },
+    ]
+  })
+  const html = renderToString(() => <UnheadContext.Provider value={unhead}><App /></UnheadContext.Provider>)
+  return { html, unhead }
+}
+```
+
+For adding tags in your components, you can either use the `useHead()`{lang="ts"} hook.
+
+```tsx [App.tsx]
+import { Head, useHead } from '@unhead/solid-js'
+
+export default function App() {
+  // a. use the hook
+  useHead({
+    title: 'My Awesome Site',
+    meta: [
+      { name: 'description', content: 'My awesome site description' }
+    ]
+  })
+  // b. use the component
+  return (
+    <div>
+      <Head>
+        <title>My Awesome Site</title>
+        <meta name="description" content="My awesome site description" />
+      </Head>
+      <h1>Hello World</h1>
+    </div>
+  )
+}
+```
+
+### 5. Optional: Auto-Imports
+
+If you're using  [unplugin-auto-import](https://github.com/antfu/unplugin-auto-import), you can automatically import the composables.
+
+```ts [vite.config.ts]
+import { hookImports } from '@unhead/solid-js'
+import AutoImport from 'unplugin-auto-import/vite'
+
+export default defineConfig({
+  plugins: [
+    AutoImport({
+      imports: [
+        hookImports,
+      ],
+    }),
+    // ...
+  ]
+})
+```
+
+## Next Steps
+
+Your Solid.js app is now setup for head management, congrats! 🎉
+
+You can get started with any of the hooks or components:
+- [`useHead()`{lang="ts"}](/docs/api/use-head)
+- [`useSeoMeta()`{lang="ts"}](/docs/api/use-seo-meta)
+
+Or explore some of the optional extras:
+
+- Add [`useSchemaOrg()`{lang="ts"}](/docs/api/use-schema-org) for structured data
+- Use [`useScript()`{lang="ts"}](/docs/scripts/introduction) for performance optimized script loading