Skip to content

Commit

Permalink
Merge pull request #2 from dwyl/learn-nextra-#1
Browse files Browse the repository at this point in the history
[PR] Creating `nextra` with auth
  • Loading branch information
nelsonic authored Jul 16, 2024
2 parents 53385a7 + 8271442 commit 59a5106
Show file tree
Hide file tree
Showing 128 changed files with 31,403 additions and 2 deletions.
6 changes: 6 additions & 0 deletions .env.local-example
Original file line number Diff line number Diff line change
@@ -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
54 changes: 54 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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 }}
12 changes: 12 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
55 changes: 55 additions & 0 deletions .vscode/launch.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
]
}
3 changes: 3 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"typescript.tsdk": "node_modules/typescript/lib"
}
183 changes: 181 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -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 [email protected]: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
```
49 changes: 49 additions & 0 deletions jest.config.ts
Original file line number Diff line number Diff line change
@@ -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);
6 changes: 6 additions & 0 deletions next-env.d.ts
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions next.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
const withNextra = require("nextra")({
theme: "./theme/src/index.tsx",
themeConfig: "./theme.config.tsx",
defaultShowCopyCode: true
});

module.exports = withNextra();
Loading

0 comments on commit 59a5106

Please sign in to comment.