Merge pull request #2 from dwyl/learn-nextra-#1

[PR] Creating `nextra` with auth

.env.local-example

@@ -0,0 +1,6 @@
+# Added by `npx auth secret`. Read: cli.authjs.dev
+AUTH_SECRET="xYZIaxb3/4vWVFHO91ei850HX1c+4xt4LDg+HrEua2g="
+# github.com/dwyl/elixir-auth-github/blob/main/create-github-app-guide.md
+AUTH_GITHUB_ID=Ov23liOrClObMkul48XYZ
+AUTH_GITHUB_SECRET=abc651709a5fd30146e55aa143b4831491df931d
+TEST_PASSWORD=supercalifragilisticexpialidocious

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: Build & Test
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+jobs:
+  ci:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+
+    # Setup environment (Node and pnpm)
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: lts/*
+    - uses: pnpm/action-setup@v4
+      with:
+        version: latest
+
+    # Install dependencies
+    - name: Install dependencies
+      run: pnpm install --no-frozen-lockfile
+
+    # Run build
+    - name: Build Next.js app
+      run: pnpm run build
+
+    # Run unit tests
+    - name: Running unit tests
+      run: pnpm run test
+
+    # Run E2E tests
+    - name: Install Playwright Browsers
+      run: pnpm exec playwright install --with-deps
+    - name: Run Playwright tests
+      run: pnpm exec playwright test
+      env:
+        AUTH_SECRET: some_nextauth_secret
+        TEST_PASSWORD: password
+
+    - uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: playwright-report
+        path: playwright-report/
+        retention-days: 30
+
+    # Upload coverage to Codecov
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -128,3 +128,15 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+/e2e-test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+
+# Playwright
+/test-results/
+/e2e-test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/.swc

.vscode/launch.json

@@ -0,0 +1,55 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "type": "node-terminal",
+        "name": "Debug Current TS File (ts-node)",
+        "request": "launch",
+        "command": "npx ts-node -- ${fileBasenameNoExtension}",
+        "cwd": "${fileDirname}"
+      },
+      {
+        "name": "Jest file",
+        "type": "pwa-node",
+        "request": "launch",
+        "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/jest",
+        "args": [
+            "${fileBasenameNoExtension}",
+            "--runInBand",
+            "--watch",
+            "--coverage=false",
+            "--no-cache"
+        ],
+        "cwd": "${workspaceRoot}",
+        "console": "integratedTerminal",
+        "internalConsoleOptions": "neverOpen",
+        "sourceMaps": true,
+        "windows": {
+            "program": "${workspaceFolder}/node_modules/jest/bin/jest"
+        }
+    },
+      {
+        "name": "Next.js: debug server-side",
+        "type": "node-terminal",
+        "request": "launch",
+        "command": "pnpm run dev"
+      },
+      {
+        "name": "Next.js: debug client-side",
+        "type": "chrome",
+        "request": "launch",
+        "url": "http://localhost:3000"
+      },
+      {
+        "name": "Next.js: debug full stack",
+        "type": "node-terminal",
+        "request": "launch",
+        "command": "pnpm run dev",
+        "serverReadyAction": {
+          "pattern": "- Local:.+(https?://.+)",
+          "uriFormat": "%s",
+          "action": "debugWithChrome"
+        }
+      }
+    ]
+  }

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "typescript.tsdk": "node_modules/typescript/lib"
+}

README.md

@@ -1,2 +1,181 @@
-# nextra-demo
-A comprehensive demo of using nextra for a documentation site with Auth (private pages), Search and Analytics!
+<div align="center">
+
+# `Nextra` _Demo_
+
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dwyl/nextra-demo/ci.yml?label=build&style=flat-square&branch=main)
+[![codecov.io](https://img.shields.io/codecov/c/github/dwyl/nextra-demo/main.svg?style=flat-square)](https://codecov.io/github/dwyl/nextra-demo?branch=main)
+[![HitCount](https://hits.dwyl.com/dwyl/nextra-demo.svg?style=flat-square)](https://hits.dwyl.com/dwyl/nextra-demo)
+[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat-square)](https://github.com/dwyl/nextra-demo/issues)
+
+A comprehensive demo / tutorial
+using `Nextra` for a documentation site <br />
+with
+**authentication**
+(private pages),
+search and analytics!
+
+</div>
+
+<!--
+Note: the Table of Contents is auto-generated/updated by Markdown All-in-One 
+https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
+-->
+
+- [`Nextra` _Demo_](#nextra-demo)
+- [Why? 🤷‍♀️](#why-️)
+- [What? ✨](#what-)
+- [Who? 👥](#who-)
+- [How? 👩‍💻](#how-)
+    - [1. Clone the Project](#1-clone-the-project)
+    - [2. Install Dependencies](#2-install-dependencies)
+    - [3. Create Environment Variables](#3-create-environment-variables)
+    - [4. Run the App!](#4-run-the-app)
+  - [Run the Tests!](#run-the-tests)
+  - [Build It!](#build-it)
+  - [_Please_ star the repo! ⭐️](#please-star-the-repo-️)
+  - [Troubleshooting](#troubleshooting)
+
+
+# Why? 🤷‍♀️
+
+Working as a software engineer,
+you come across technical documentation daily.
+From API references to internal manuals,
+technical documentation
+**is vital for the development process**.
+Everyone expects docs as a
+[hygiene factor](https://en.wikipedia.org/wiki/Two-factor_theory#:~:text=Hygiene%20factors).
+Without docs,
+knowledge of the application becomes siloed
+and means you cannot scale your team
+or continue in the event of someone leaving!
+
+Great docs ensure long-term sustainability of your software projects.
+Having a clear record
+of the `why`, `how` and `what`
+helps maintain consistency
+and increases the quality of your work!
+
+Whether it is meant as an internal reference
+or you're creating documentation for public-facing clients
+that are using your project,
+having documentation benefits both the developers and users alike.
+
+
+# What? ✨
+
+[`Nextra`](https://nextra.site/) is a framework
+that makes it easy for you to create a documentation static website
+fully optimized and powered by 
+[`Next.js`](https://github.com/dwyl/learn-nextjs).
+
+It simpifies the process of creating and maintaining documentation
+by offering a myriad of features, such as:
+- Themeable design system.
+- Markdown and [`MDX`](https://nextra.site/docs/guide/markdown) support.
+- Full-text search out-of-the-box.
+- Automatic [`a11y`](https://www.a11yproject.com/).
+- Filesystem-based organization.
+
+The integration with
+[`Next.js`](https://github.com/dwyl/learn-nextjs)
+makes `Nextra` fully customizable,
+thus ideal for your team
+to quickly generate a website
+that is useful for both internal and external stakeholders.
+
+# Who? 👥
+
+This walkthrough is meant for beginners
+and seasoned software engineers alike
+who want to create internal and external
+documentation for their teams.
+
+This will **not be an introduction to technical writing**,
+it will solely focus on the `Nextra` framework.
+We recommend visiting 
+[developers.google.com/tech-writing](https://developers.google.com/tech-writing/overview)
+if you are interested in learning more about technical writing.
+
+If you find it useful, please give the repo a star! ⭐️
+
+If you get stuck, have questions/suggestions
+or just want to discuss this further,
+[please open an issue](https://github.com/dwyl/nextra-demo/issues)!
+
+# How? 👩‍💻 
+
+Ready? Let's go! 🚀
+
+## Run the _Finished_ Project
+
+### 1. Clone the Project
+
+In your terminal, 
+run the following command to clone the repo:
+
+```sh
+git clone git@github.com:dwyl/nextra-demo.git && cd nextra-demo
+```
+
+### 2. Install Dependencies
+
+Run:
+
+```sh
+npm i
+```
+
+### 3. Create Environment Variables
+
+Copy the `.env.local-example` file and create your `.env.local` file:
+
+```sh
+cp .env.local-example .env.local
+```
+
+Add the necessary environment variables to your `.env.local` file,
+e.g: 
+
+```sh
+
+```
+
+
+
+### 4. Run the App!
+
+
+Open your web browser to:
+
+
+
+## Run the Tests!
+
+Run the tests with the following command:
+
+```sh
+
+```
+
+## Build It!
+
+Ready to _build_ it yourself?!
+See:
+[tutorial.md](./tutorial.md)
+
+
+## _Please_ star the repo! ⭐️
+
+If you find this repo/tutorial useful,
+please star it on GitHub, so that we know! ⭐
+
+Thank you! 🙏
+
+
+## Troubleshooting
+
+```sh
+[auth][error] MissingSecret: Please define a `secret`.. 
+  Read more at https://errors.authjs.dev#missingsecret
+```

jest.config.ts

@@ -0,0 +1,49 @@
+/**
+ * For a detailed explanation regarding each configuration property, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+import type { Config } from "jest";
+import nextJest from "next/jest.js";
+
+const createJestConfig = nextJest({
+  // Provide the path to your Next.js app to load next.config.js and .env files in your test environment
+  dir: "./",
+});
+
+const config: Config = {
+  collectCoverage: true,
+  collectCoverageFrom: ["src/**/*.{js,jsx,ts,tsx}", "!<rootDir>/node_modules/"],
+  coverageDirectory: "coverage",
+  coveragePathIgnorePatterns: ["/node_modules/"],
+  coverageProvider: "v8",
+
+  moduleDirectories: [
+    "node_modules"
+  ],
+  modulePathIgnorePatterns: [
+    // Testing auth with `next-auth` complains (consider switching to Vitest)
+    // Doesn't seem to have a proper solution. See https://github.com/nextauthjs/next-auth/issues/4198.
+    "src/auth.ts",
+
+    // Middleware can't be properly mocked to test.
+    "src/middleware.ts",
+
+    // No need to unit test types
+    "src/types.ts",
+
+    // The "_app.ts" runs on every page and can't be properly tested. There's no need to, regardless.
+    "src/pages/_app.ts",
+
+    // The `app` folder is only used to export the default handlers from `next-auth`.
+    "src/app"
+  ],
+  moduleNameMapper: {
+    "next-auth/(.*)": "<rootDir>/node_modules/next-auth/$1",
+  },
+
+  testEnvironment: "jsdom",
+  testPathIgnorePatterns: ["tests/e2e"],
+};
+
+export default createJestConfig(config);

next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference types="next/navigation-types/compat/navigation" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.

next.config.js

@@ -0,0 +1,7 @@
+const withNextra = require("nextra")({
+  theme: "./theme/src/index.tsx",
+  themeConfig: "./theme.config.tsx",
+  defaultShowCopyCode: true
+});
+
+module.exports = withNextra();