feat(astro): override components to support HeadTags (#375)

eric-burel · web-flow · commit e93d11a11b8a · 2024-10-16T09:54:35.000+03:00
diff --git a/docs/tutorialkit.dev/src/content/docs/guides/overriding-components.mdx b/docs/tutorialkit.dev/src/content/docs/guides/overriding-components.mdx
@@ -89,4 +89,22 @@ interface Props {
   /** Content of the dialog */
   children: ReactNode;
 }
+```
+
+### HeadTags
+
+Component for overriding title, links and metadata in the `<head>` tag.
+
+When overriding `HeadTags` you can place TutorialKit's default components using following [Astro slots](https://docs.astro.build/en/basics/astro-components/#named-slots):
+
+- `title`: The page title
+- `links`: Links for the favicon, fonts and other assets
+- `meta`:  Metadata and Open Graph tags
+
+```jsx title="src/components/CustomHeadLinks.astro"
+<slot name="title" />
+<slot name="links" />
+<slot name="meta" />
+{/** Add your own tags */}
+<link rel="sitemap" href="/sitemap-index.xml" />
 ```
diff --git a/e2e/configs/override-components.ts b/e2e/configs/override-components.ts
@@ -10,6 +10,7 @@ export default defineConfig({
       components: {
         Dialog: './src/components/Dialog.tsx',
         TopBar: './src/components/TopBar.astro',
+        HeadTags: './src/components/CustomHeadTags.astro',
       },
     }),
   ],
diff --git a/e2e/src/components/CustomHeadTags.astro b/e2e/src/components/CustomHeadTags.astro
@@ -0,0 +1,5 @@
+<slot name="title" />
+<slot name="links" />
+<slot name="meta" />
+<meta name="e2e-test-custom-meta-tag" content="custom-content" />
+<link rel="sitemap" href="/sitemap-index.xml" />
diff --git a/e2e/test/headtags.override-components.test.ts b/e2e/test/headtags.override-components.test.ts
@@ -0,0 +1,23 @@
+import { test, expect } from '@playwright/test';
+
+test('developer can override HeadTags', async ({ page }) => {
+  await page.goto('/');
+
+  const defaultElems = [
+    page.locator('title'),
+    page.locator('meta[name="og:title"]'),
+    page.locator('link[rel="stylesheet"]').first(),
+  ];
+  const customElems = [
+    page.locator('meta[name="e2e-test-custom-meta-tag"][content="custom-content"]'),
+    page.locator('link[rel="sitemap"]'),
+  ];
+
+  for (const e of defaultElems) {
+    await expect(e).toBeAttached();
+  }
+
+  for (const e of customElems) {
+    await expect(e).toBeAttached();
+  }
+});
diff --git a/packages/astro/package.json b/packages/astro/package.json
@@ -20,6 +20,7 @@
     "./default/pages/index.astro": "./dist/default/pages/index.astro",
     "./default/pages/[...slug].astro": "./dist/default/pages/[...slug].astro",
     "./default/components/TopBar.astro": "./dist/default/components/TopBar.astro",
+    "./default/components/HeadTags.astro": "./dist/default/components/HeadTags.astro",
     "./package.json": "./package.json"
   },
   "files": [
diff --git a/packages/astro/src/default/components/HeadTags.astro b/packages/astro/src/default/components/HeadTags.astro
@@ -0,0 +1,3 @@
+<slot name="title" />
+<slot name="links" />
+<slot name="meta" />
diff --git a/packages/astro/src/default/env-default.d.ts b/packages/astro/src/default/env-default.d.ts
@@ -9,9 +9,10 @@ interface WebContainerConfig {
 
 declare module 'tutorialkit:override-components' {
   const topBar: typeof import('./src/default/components/TopBar.astro').default;
+  const headTags: typeof import('./src/default/components/HeadTags.astro').default;
   const dialog: typeof import('@tutorialkit/react/dialog').default;
 
-  export { topBar as TopBar, dialog as Dialog };
+  export { topBar as TopBar, dialog as Dialog, headTags as HeadTags };
 }
 
 declare const __ENTERPRISE__: boolean;
diff --git a/packages/astro/src/default/layouts/Layout.astro b/packages/astro/src/default/layouts/Layout.astro
@@ -1,4 +1,5 @@
 ---
+import { HeadTags } from 'tutorialkit:override-components';
 import { ViewTransitions } from 'astro:transitions';
 import type { MetaTagsConfig } from '@tutorialkit/types';
 import MetaTags from '../components/MetaTags.astro';
@@ -15,13 +16,22 @@ const faviconUrl = readPublicAsset('favicon.svg');
 <!doctype html>
 <html lang="en" transition:animate="none" class="h-full overflow-hidden">
   <head>
-    <title>{title}</title>
-    {faviconUrl ? <link rel="icon" type="image/svg+xml" href={faviconUrl} /> : null}
-    <MetaTags meta={meta} />
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
-    <link href="https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400;700&display=swap" rel="stylesheet" />
+    <HeadTags>
+      <title slot="title">{title}</title>
+
+      <Fragment slot="links">
+        {faviconUrl ? <link rel="icon" type="image/svg+xml" href={faviconUrl} /> : null}
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+          rel="stylesheet"
+        />
+        <link href="https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400;700&display=swap" rel="stylesheet" />
+      </Fragment>
+
+      <MetaTags slot="meta" meta={meta} />
+    </HeadTags>
     <ViewTransitions />
     <script is:inline>
       setTutorialKitTheme();
diff --git a/packages/astro/src/vite-plugins/override-components.ts b/packages/astro/src/vite-plugins/override-components.ts
@@ -18,6 +18,7 @@
  *       components: {
  *         TopBar: './CustomTopBar.astro',
  *         Dialog: './CustomDialog.tsx',
+ *         HeadTags: './CustomHeadLinks.astro',
  *       },
  *     }),
  *   ],
@@ -54,6 +55,23 @@ export interface OverrideComponentsOptions {
    * It will receive same props that `@tutorialkit/react/dialog` supports.
    */
   Dialog?: string;
+
+  /**
+   * Component for overriding title, links and metadata in the `<head>` tag.
+   *
+   * This component has slots that are used to pass TutorialKit's default tags:
+   *
+   * - `title`: The page title
+   * - `links`: Links for the favicon, fonts and other assets
+   * - `meta`:  Metadata and Open Graph tags
+   *
+   * ```jsx
+   * <slot name="title" />
+   * <slot name="links" />
+   * <slot name="meta" />
+   * ```
+   */
+  HeadTags: string;
 }
 
 interface Options {
@@ -77,11 +95,13 @@ export function overrideComponents({ components, defaultRoutes }: Options): Vite
     async load(id) {
       if (id === resolvedId) {
         const topBar = components?.TopBar || resolveDefaultTopBar(defaultRoutes);
+        const headTags = components?.HeadTags || resolveDefaultHeadTags(defaultRoutes);
         const dialog = components?.Dialog || '@tutorialkit/react/dialog';
 
         return `
           export { default as TopBar } from '${topBar}';
           export { default as Dialog } from '${dialog}';
+          export { default as HeadTags } from '${headTags}';
         `;
       }
 
@@ -98,3 +118,12 @@ function resolveDefaultTopBar(defaultRoutes: boolean) {
   // default `TopBar` is used from local file when `defaultRoutes` is disabled
   return './src/components/TopBar.astro';
 }
+
+function resolveDefaultHeadTags(defaultRoutes: boolean) {
+  if (defaultRoutes) {
+    return '@tutorialkit/astro/default/components/HeadTags.astro';
+  }
+
+  // default `HeadTags` is used from local file when `defaultRoutes` is disabled
+  return './src/components/HeadTags.astro';
+}
diff --git a/packages/cli/tests/__snapshots__/create-tutorial.test.ts.snap b/packages/cli/tests/__snapshots__/create-tutorial.test.ts.snap
@@ -235,6 +235,7 @@ exports[`create and eject a project 1`] = `
   "public/logo.svg",
   "src",
   "src/components",
+  "src/components/HeadTags.astro",
   "src/components/LoginButton.tsx",
   "src/components/Logo.astro",
   "src/components/MainContainer.astro",

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+<slot name="title" />`
	`2`	`+<slot name="links" />`
	`3`	`+<slot name="meta" />`
Original file line number	Diff line number	Diff line change
`@@ -9,9 +9,10 @@ interface WebContainerConfig {`
`9`	`9`
`10`	`10`	`declare module 'tutorialkit:override-components' {`
`11`	`11`	`const topBar: typeof import('./src/default/components/TopBar.astro').default;`
	`12`	`+ const headTags: typeof import('./src/default/components/HeadTags.astro').default;`
`12`	`13`	`const dialog: typeof import('@tutorialkit/react/dialog').default;`
`13`	`14`
`14`		`- export { topBar as TopBar, dialog as Dialog };`
	`15`	`+ export { topBar as TopBar, dialog as Dialog, headTags as HeadTags };`
`15`	`16`	`}`
`16`	`17`
`17`	`18`	`declare const __ENTERPRISE__: boolean;`