[core][s]: darkmode storybook addon

Tutorial 4 (overview): Customising your website locally and previewing your changes locally

nx.json

@@ -5,7 +5,13 @@
     "default": {
       "runner": "nx/tasks-runners/default",
       "options": {
-        "cacheableOperations": ["build", "lint", "test", "e2e"]
+        "cacheableOperations": [
+          "build",
+          "lint",
+          "test",
+          "e2e",
+          "build-storybook"
+        ]
       }
     }
   },
@@ -30,6 +36,14 @@
         "{workspaceRoot}/.eslintrc.json",
         "{workspaceRoot}/.eslintignore"
       ]
+    },
+    "build-storybook": {
+      "inputs": [
+        "default",
+        "^production",
+        "{projectRoot}/.storybook/**/*",
+        "{projectRoot}/tsconfig.storybook.json"
+      ]
     }
   },
   "namedInputs": {
@@ -39,7 +53,10 @@
       "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
       "!{projectRoot}/tsconfig.spec.json",
       "!{projectRoot}/jest.config.[jt]s",
-      "!{projectRoot}/.eslintrc.json"
+      "!{projectRoot}/.eslintrc.json",
+      "!{projectRoot}/**/*.stories.@(js|jsx|ts|tsx|mdx)",
+      "!{projectRoot}/.storybook/**/*",
+      "!{projectRoot}/tsconfig.storybook.json"
     ],
     "sharedGlobals": ["{workspaceRoot}/babel.config.json"]
   },

package.json

@@ -20,10 +20,20 @@
     "@nrwl/js": "15.9.2",
     "@nrwl/linter": "15.9.2",
     "@nrwl/next": "15.9.2",
-    "@nrwl/react": "15.9.2",
+    "@nrwl/react": "^15.9.2",
     "@nrwl/rollup": "15.9.2",
+    "@nrwl/storybook": "15.9.2",
+    "@nrwl/webpack": "15.9.2",
     "@nrwl/workspace": "15.9.2",
+    "@nx/js": "16.6.0",
     "@rollup/plugin-url": "^7.0.0",
+    "@storybook/addon-essentials": "7.0.18",
+    "@storybook/addon-interactions": "7.0.18",
+    "@storybook/core-server": "7.0.18",
+    "@storybook/jest": "~0.1.0",
+    "@storybook/react-webpack5": "^7.0.18",
+    "@storybook/test-runner": "^0.11.0",
+    "@storybook/testing-library": "~0.2.0",
     "@svgr/rollup": "^6.1.2",
     "@swc/core": "^1.2.173",
     "@swc/helpers": "~0.5.0",
@@ -39,6 +49,7 @@
     "@typescript-eslint/parser": "^5.36.1",
     "babel-jest": "^29.4.1",
     "chai": "^4.3.7",
+    "core-js": "^3.6.5",
     "cypress": "^12.2.0",
     "eslint": "~8.15.0",
     "eslint-config-next": "13.1.1",
@@ -58,11 +69,16 @@
     "react-test-renderer": "18.2.0",
     "rehype-stringify": "^9.0.3",
     "remark": "^14.0.3",
+    "storybook-tailwind-dark-mode": "^1.0.22",
     "swc-loader": "0.1.15",
     "ts-jest": "^29.0.5",
     "ts-node": "10.9.1",
     "typescript": "~4.9.5",
     "unist-util-select": "^4.0.3",
     "unist-util-visit": "^4.1.2"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   }
 }

packages/components/.storybook/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /$
+Disallow: /

packages/components/package.json

@@ -16,7 +16,7 @@
     "build": "tsc && vite build && npm run build-tailwind && npm run fix-leaflet",
     "lint": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build",
+    "build-storybook": "storybook build && cp ./.storybook/robots.txt ./storybook-static",
     "build-tailwind": "NODE_ENV=production npx tailwindcss --postcss -c tailwind.config.js -i src/index.css -o ./dist/style.css --minify",
     "prepare": "npm run build",
     "fix-leaflet": "node ./scripts/fix-leaflet.cjs"

packages/core/.storybook/main.ts

@@ -0,0 +1,21 @@
+import type { StorybookConfig } from '@storybook/react-webpack5';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+    '@nrwl/react/plugins/storybook',
+    'storybook-tailwind-dark-mode'
+  ],
+  framework: {
+    name: '@storybook/react-webpack5',
+    options: {},
+  },
+};
+
+export default config;
+
+// To customize your webpack configuration you can use the webpackFinal field.
+// Check https://storybook.js.org/docs/react/builders/webpack#extending-storybooks-webpack-config
+// and https://nx.dev/packages/storybook/documents/custom-builder-configs

packages/core/.storybook/preview.ts

@@ -0,0 +1,14 @@
+import './tailwind-imports.css';
+
+const preview = {
+    globalTypes: {
+        darkMode: {
+            defaultValue: false, // Enable dark mode by default on all stories
+        },
+        className: {
+            defaultValue: 'dark', // Set your custom dark mode class name
+        },
+    },
+};
+
+export default preview;

packages/core/.storybook/tailwind-imports.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

packages/core/.storybook/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "emitDecoratorMetadata": true,
+    "outDir": ""
+  },
+  "files": [
+    "../../node_modules/@nx/react/typings/styled-jsx.d.ts",
+    "../../node_modules/@nx/react/typings/cssmodule.d.ts",
+    "../../node_modules/@nx/react/typings/image.d.ts"
+  ],
+  "exclude": [
+    "src/**/*.spec.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.js",
+    "src/**/*.test.js",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.test.js"
+  ],
+  "include": [
+    "src/**/*.stories.ts",
+    "src/**/*.stories.js",
+    "src/**/*.stories.jsx",
+    "src/**/*.stories.tsx",
+    "src/**/*.stories.mdx",
+    ".storybook/*.js",
+    ".storybook/*.ts"
+  ]
+}

packages/core/postcss.config.js

@@ -0,0 +1,11 @@
+// libs/shared/ui/postcss.config.js
+const { join } = require('path');
+
+module.exports = {
+  plugins: {
+    tailwindcss: {
+      config: join(__dirname, 'tailwind.config.js'),
+    },
+    autoprefixer: {},
+  },
+};

packages/core/project.json

@@ -34,6 +34,37 @@
         "jestConfig": "packages/core/jest.config.ts",
         "passWithNoTests": true
       }
+    },
+    "storybook": {
+      "executor": "@nrwl/storybook:storybook",
+      "options": {
+        "port": 4400,
+        "configDir": "packages/core/.storybook"
+      },
+      "configurations": {
+        "ci": {
+          "quiet": true
+        }
+      }
+    },
+    "build-storybook": {
+      "executor": "@nrwl/storybook:build",
+      "outputs": ["{options.outputDir}"],
+      "options": {
+        "outputDir": "dist/storybook/core",
+        "configDir": "packages/core/.storybook"
+      },
+      "configurations": {
+        "ci": {
+          "quiet": true
+        }
+      }
+    },
+    "test-storybook": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "test-storybook -c packages/core/.storybook --url=http://localhost:4400"
+      }
     }
   }
 }

packages/core/src/ui/Card/Card.stories.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Card } from './Card';
+
+const meta: Meta<typeof Card> = {
+    component: Card,
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+/*
+ *👇 Render functions are a framework specific feature to allow you control on how the component renders.
+ * See https://storybook.js.org/docs/react/api/csf
+ * to learn how to use render functions.
+ */
+
+const blog = {
+    urlPath: "#",
+    title: "Card title goes here",
+    date: "2021-01-01",
+    description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, diam quis accumsan maximus, quam libero porttitor nisl, vita",
+}
+
+export const Primary: Story = {
+    render: () => (
+        <Card className="md:col-span-3">
+            <Card.Title href={`${blog.urlPath}`}>
+                {blog.title}
+            </Card.Title>
+            <Card.Eyebrow
+                as="time"
+                dateTime={blog.date}
+                className="md:hidden"
+                decorate
+            >
+                {blog.date}
+            </Card.Eyebrow>
+            {blog.description && (
+                <Card.Description>
+                    {blog.description}
+                </Card.Description>
+            )}
+            <Card.Cta>Read article</Card.Cta>
+        </Card>
+    ),
+};

packages/core/tailwind.config.js

@@ -0,0 +1,44 @@
+const { createGlobPatternsForDependencies } = require('@nrwl/next/tailwind');
+const { join } = require('path');
+// const defaultTheme = require("tailwindcss/defaultTheme");
+const colors = require("tailwindcss/colors");
+
+module.exports = {
+  content: [
+    join(__dirname, './src/**/*.{js,ts,jsx,tsx}'),
+    ...createGlobPatternsForDependencies(__dirname),
+  ],
+  darkMode: "class",
+  theme: {
+    extend: {
+      // support wider width for large screens >1440px eg. in hero
+      maxWidth: {
+        "8xl": "88rem",
+      },
+      // fontFamily: {
+      //   sans: ["ui-sans-serif", ...defaultTheme.fontFamily.sans],
+      //   serif: ["ui-serif", ...defaultTheme.fontFamily.serif],
+      //   mono: ["ui-monospace", ...defaultTheme.fontFamily.mono],
+      //   headings: ["-apple-system", ...defaultTheme.fontFamily.sans],
+      // },
+      colors: {
+        background: {
+          DEFAULT: colors.white,
+          dark: colors.slate[900],
+        },
+        primary: {
+          DEFAULT: colors.gray[700],
+          dark: colors.gray[300],
+        },
+        secondary: {
+          DEFAULT: colors.sky[400],
+          dark: colors.sky[400],
+        },
+      },
+    },
+  },
+  /* eslint global-require: off */
+  // plugins: [
+  //   require("@tailwindcss/typography")
+  // ],
+};

packages/core/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "baseUrl": ".",
     "jsx": "react-jsx",
     "module": "es2020",
     "moduleResolution": "node",
@@ -22,6 +23,9 @@
     },
     {
       "path": "./tsconfig.spec.json"
+    },
+    {
+      "path": "./.storybook/tsconfig.json"
     }
   ]
 }

packages/core/tsconfig.lib.json

@@ -17,7 +17,11 @@
     "**/*.spec.js",
     "**/*.test.js",
     "**/*.spec.jsx",
-    "**/*.test.jsx"
+    "**/*.test.jsx",
+    "**/*.stories.ts",
+    "**/*.stories.js",
+    "**/*.stories.jsx",
+    "**/*.stories.tsx"
   ],
   "include": ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"]
 }

site/content/guide/index.md

@@ -135,6 +135,56 @@ By the end of this tutorial, you will:
 > [!tip]
 > Read full tutorial [[collaborate-on-website-project|here!]] (TBD)
 
+### Tutorial 4: Customising your website locally and previewing your changes locally
+
+In this tutorial, we will dive into the more technical aspects of website customisation, but this time, everything will be done locally. You'll learn how to preview your site on your own machine before pushing changes to the live site, ensuring everything looks and works exactly as you want.
+
+By the end of this tutorial, you will:
+
+- Understand how to preview your site locally.
+- Know how to change your website's title and description.
+- Learn how to customise your website's appearance using Tailwind themes.
+- Understand how to configure the navbar, navigation links, and logo.
+- Learn how to integrate Google Analytics into your website.
+- Be aware of additional customisation options for deeper customisation.
+
+#### Previewing the site locally
+
+- Navigate to your website's repository directory on your computer using command line
+- Install the site's dependencies
+- Start the local development server
+- Visit the local address displayed in your command line. Yay! You can now preview your changes locally, live! 🎉
+
+#### Changing the site title and description
+
+- Perfect! You've personalised your site's title and description! 🎉
+
+#### Configuring the title, description and navbar
+
+- Open the `content/config.mjs` file in your code editor
+- Edit the `title` and `description` fields
+- Edit the fields in the `navbar` field to customise your navbar's title and logo. Then, add navigation links to `navLinks` field (these will be displayed in the navbar). Save and refresh your local site to see the changes.
+
+#### Integrating with Google Analytics
+
+- Still in the `content/config.mjs` file, navigate to the `analytics` field
+- Enter your Google Analytics tracking ID, save and refresh your local site to ensure it's integrated correctly
+- Excellent! Your website is now integrated with Google Analytics! 🎉
+
+#### Customising the Tailwind theme
+
+- Open `tailwind.config.js` file in your code editor
+- Change the light and dark theme colours and fonts to your liking, save and refresh your local site to see the changes
+- Awesome! Your website now has a new look! 🎉
+
+When you're happy with all your changes, use GitHub Desktop to commit your changes and push them back to your GitHub repository.
+
+In addition to these topics, the full tutorial shows you what other customisations options are available and where to find information on these.
+
+> [!tip]
+> Read full tutorial here! (TBD)
+
+
 ## Howtos
 
 - [[quickly-create-a-sandbox-website|How to quickly create a sandbox website]]

site/next-sitemap.config.js

@@ -2,4 +2,10 @@
 module.exports = {
   siteUrl: process.env.SITE_URL || 'https://portaljs.org',
   generateRobotsTxt: true,
-}
+  robotsTxtOptions: {
+    policies: [
+      { userAgent: '*', disallow: '/people' },
+      { userAgent: '*', disallow: '/?amp=1' },
+    ],
+  },
+};

tsconfig.base.json

@@ -15,10 +15,10 @@
     "skipDefaultLibCheck": true,
     "baseUrl": ".",
     "paths": {
+      "@portaljs/core": ["packages/core/src/index.ts"],
       "@portaljs/portaljs-components": [
         "packages/portaljs-components/src/index.ts"
-      ],
-      "@portaljs/core": ["packages/core/src/index.ts"]
+      ]
     }
   },
   "exclude": ["node_modules", "tmp"]