chore(example): add @auth/express example app (#9570)

rexfordessilfie · ndom91 · web-flow · commit 9e802b00fdfb · 2024-01-15T02:41:15.000+01:00
* feat: add @auth/express dev app

* test: add signin e2e spec

* chore: update pnpm-lock

* refactor: move express app to examples

* chore: rename files plus load env before import app

* chore: update signed in layout banner

* chore: update pnpm-lock

* chore: add comment for credentials validator

* fix: missing pug view engine

* chore: cleanup server callbacks

* chore: update dev concurrently tags

* docs: standardize express auth example readme

* chore: update error handler errors

* test: no e2e in example

* chore: cleanup scripts

* docs: add section on node.js compatibility to express example

* chore: remove credentials provider

* docs: add comment on rate-limiting for authentication routes

* chore: use AuthConfig type

* chore: add node engine plus remove experimental flags

* refactor: cleanup globals

* chore: tsconfig module + moduleResolution -&gt; nodenext to support cjs require

* docs: remove experimental fetch discussion and include crypto polyfill

* chore: temp include @auth/core dep

* chore: remove name and version

* chore: update gitignore

* docs: update express img link

* chore: add node types

* feat: vercel ready express example

* chore: cleanup

* docs: update host copy

* chore: remove @auth/core dependency

* chore: add viewport meta

* feat: sync example app

---------

Co-authored-by: Nico Domino &lt;yo@ndo.dev&gt;
diff --git a/.github/sync.yml b/.github/sync.yml
@@ -1,3 +1,10 @@
+nextauthjs/express-auth-example:
+  - source: apps/examples/express
+    dest: .
+    deleteOrphaned: true
+  - .github/FUNDING.yml
+  - LICENSE
+
 nextauthjs/sveltekit-auth-example:
   - source: apps/examples/sveltekit
     dest: .
diff --git a/apps/examples/express/.env.example b/apps/examples/express/.env.example
@@ -0,0 +1,7 @@
+AUTH_SECRET=
+
+AUTH_GITHUB_ID=
+AUTH_GITHUB_SECRET=
+
+AUTH_GOOGLE_ID=
+AUTH_GOOGLE_SECRET=
diff --git a/apps/examples/express/.eslintrc.cjs b/apps/examples/express/.eslintrc.cjs
@@ -0,0 +1,26 @@
+module.exports = {
+  root: true,
+  env: {
+    browser: true,
+    es2021: true,
+  },
+  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  overrides: [
+    {
+      env: {
+        node: true,
+      },
+      files: [".eslintrc.{js,cjs}"],
+      parserOptions: {
+        sourceType: "script",
+      },
+    },
+  ],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    ecmaVersion: "latest",
+    sourceType: "module",
+  },
+  plugins: ["@typescript-eslint"],
+  rules: {},
+}
diff --git a/apps/examples/express/.gitignore b/apps/examples/express/.gitignore
@@ -0,0 +1,21 @@
+# API keys and secrets
+.env
+
+# Dependency directory
+node_modules
+
+# Editors
+.idea
+*.iml
+.vscode/settings.json
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Ignore built ts files
+dist/**/*
+
+# Ignore built css files
+/public/css/output.css
+
diff --git a/apps/examples/express/.prettierignore b/apps/examples/express/.prettierignore
@@ -0,0 +1,14 @@
+
+.DS_Store
+node_modules
+/dist
+/.turbo
+/package
+.env
+.env.*
+!.env.example
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
diff --git a/apps/examples/express/.prettierrc b/apps/examples/express/.prettierrc
@@ -0,0 +1,5 @@
+{
+  "semi": false,
+  "plugins": ["@prettier/plugin-pug", "prettier-plugin-tailwindcss"],
+  "pugClassNotation": "attribute"
+}
diff --git a/apps/examples/express/README.md b/apps/examples/express/README.md
@@ -0,0 +1,63 @@
+> The example repository is maintained from a [monorepo](https://github.com/nextauthjs/next-auth/tree/main/apps/examples/express). Pull Requests should be opened against [`nextauthjs/next-auth`](https://github.com/nextauthjs/next-auth).
+
+<p align="center">
+   <br/>
+   <a href="https://authjs.dev" target="_blank">
+   <img height="64" src="https://authjs.dev/img/logo/logo-sm.png" />
+   </a>
+   <a href="https://expressjs.com" target="_blank">
+   <img height="64" src="https://i.cloudup.com/zfY6lL7eFa-3000x3000.png" />
+   </a>
+   <h3 align="center"><b>Express Auth</b> - Example App</h3>
+   <p align="center">
+   Open Source. Full Stack. Own Your Data.
+   </p>
+   <p align="center" style="align: center;">
+      <a href="https://npm.im/@auth/express">
+        <img alt="npm" src="https://img.shields.io/npm/v/@auth/express?color=green&label=@auth/express&style=flat-square">
+      </a>
+      <a href="https://bundlephobia.com/result?p=@auth/express">
+        <img src="https://img.shields.io/bundlephobia/minzip/@auth/express?label=size&style=flat-square" alt="Bundle Size"/>
+      </a>
+      <a href="https://www.npmtrends.com/@auth/express">
+        <img src="https://img.shields.io/npm/dm/@auth/express?label=downloads&style=flat-square" alt="Downloads" />
+      </a>
+      <a href="https://npm.im/@auth/express">
+        <img src="https://img.shields.io/badge/TypeScript-blue?style=flat-square" alt="TypeScript" />
+      </a>
+   </p>
+</p>
+
+## Overview
+
+This is the official Express Auth example for [Auth.js](https://express.authjs.dev).
+
+## Getting started
+
+You can instantly deploy this example to [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=express-auth-example) by clicking the following button.
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/nextauthjs/express-auth-example&project-name=express-auth-example&repository-name=express-auth-example)
+
+## Environment Variables
+
+Once deployed, kindly ensure you set all [required environment variables](https://authjs.dev/getting-started/deployment#environment-variables) in the `Environment` section of your hosting service.
+
+## Node.js Compatibility
+
+The recommended version of Node.js to use in this example is Node.js v20.0.0.
+
+If you are using a version of Node.js lower than this (for example the minimum supported node version v18.0.0), you may need to enable Web Crypto API via the `--experimental-webcrypto` flag in the `start` and `dev` scripts of your `package.json` file.
+
+Instead of using the experimental flag, you may use the following polyfill:
+
+```ts
+// polyfill.cts
+globalThis.crypto ??= require("crypto").webcrypto
+```
+
+And then import it within a top-level file in the application:
+
+```ts
+// server.ts
+import "./polyfill.cjs"
+```
diff --git a/apps/examples/express/api/index.js b/apps/examples/express/api/index.js
@@ -0,0 +1,5 @@
+import "../src/globals.js"
+
+const { app } = await import("../src/app.js")
+
+export default app
diff --git a/apps/examples/express/package.json b/apps/examples/express/package.json
@@ -0,0 +1,44 @@
+{
+  "type": "module",
+  "description": "Express Auth example app",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "private": true,
+  "scripts": {
+    "start": "node dist/server.js",
+    "build": "pnpm build:ts && pnpm build:css",
+    "build:ts": "tsc",
+    "build:css": "tailwindcss -i ./public/css/style.css -o ./public/css/output.css",
+    "build:watch": "pnpm build:ts -w & pnpm build:css -w",
+    "dev": "concurrently -k -p \"[{name}]\" -n \"Build,Node\" -c \"cyan.bold,green.bold\" \"pnpm run build:watch\" \"pnpm run dev:node\"",
+    "dev:node": "nodemon dist/server.js",
+    "lint": "eslint src/*.ts --fix",
+    "prettier": "prettier src/*.ts --write"
+  },
+  "author": "Rexford Essilfie <rexfordessilfie09@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@auth/express": "latest",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "morgan": "^1.10.0",
+    "pug": "^3.0.2",
+    "tailwindcss": "^3.4.1"
+  },
+  "devDependencies": {
+    "@prettier/plugin-pug": "^3.0.0",
+    "@types/express": "^4.17.21",
+    "@types/morgan": "^1.9.9",
+    "@types/node": "^20.10.7",
+    "@types/pug": "^2.0.10",
+    "@typescript-eslint/eslint-plugin": "^6.18.0",
+    "@typescript-eslint/parser": "^6.18.0",
+    "concurrently": "6.5.1",
+    "eslint": "^8.56.0",
+    "nodemon": "2.0.22",
+    "prettier": "3.1.1",
+    "prettier-plugin-tailwindcss": "^0.5.11",
+    "typescript": "5.3.3"
+  }
+}
diff --git a/apps/examples/express/public/css/style.css b/apps/examples/express/public/css/style.css
@@ -0,0 +1,5 @@
+@tailwind base;
+
+@tailwind components;
+
+@tailwind utilities;
diff --git a/apps/examples/express/src/app.ts b/apps/examples/express/src/app.ts
@@ -0,0 +1,76 @@
+import express, { Request, Response } from "express"
+import logger from "morgan"
+import * as path from "path"
+
+import {
+  errorHandler,
+  errorNotFoundHandler,
+} from "./middleware/error.middleware.js"
+
+import {
+  authenticatedUser,
+  currentSession,
+} from "./middleware/auth.middleware.js"
+import { ExpressAuth } from "@auth/express"
+import { authConfig } from "./config/auth.config.js"
+import * as pug from "pug"
+
+// Create Express server
+export const app = express()
+
+// Express configuration
+app.set("port", process.env.PORT || 3000)
+
+// Set up views engine and path
+// @ts-expect-error (See https://stackoverflow.com/questions/45342307/error-cannot-find-module-pug)
+app.engine("pug", pug.__express)
+app.set("views", path.join(__dirname, "../views"))
+app.set("view engine", "pug")
+
+// Trust Proxy for Proxies (Heroku, Render.com, etc)
+// https://stackoverflow.com/questions/40459511/in-express-js-req-protocol-is-not-picking-up-https-for-my-secure-link-it-alwa
+app.enable("trust proxy")
+
+app.use(logger("dev"))
+
+// Serve static files
+// NB: Uncomment this out if you want Express to serve static files for you vs. using a
+// hosting provider which does so for you (for example through a CDN).
+// app.use(express.static(path.join(__dirname, "../public")))
+
+// Parse incoming requests data
+app.use(express.urlencoded({ extended: true }))
+app.use(express.json())
+
+// Set session in res.locals
+app.use(currentSession)
+
+// Set up ExpressAuth to handle authentication
+// IMPORTANT: It is highly encouraged set up rate limiting on this route especially if
+// it is served or hosted by a traditional server (compared to a serverless function)
+app.use("/api/auth/*", ExpressAuth(authConfig))
+
+// Routes
+
+app.get("/protected", async (_req: Request, res: Response) => {
+  res.render("protected", { session: res.locals.session })
+})
+
+app.get(
+  "/api/protected",
+  authenticatedUser,
+  async (req: Request, res: Response) => {
+    res.json(res.locals.session)
+  },
+)
+
+app.get("/", async (req: Request, res: Response) => {
+  res.render("index", {
+    title: "Express Auth Example",
+    user: res.locals.session?.user,
+  })
+})
+
+// Error handlers
+app.use(errorNotFoundHandler)
+app.use(errorHandler)
diff --git a/apps/examples/express/src/config/auth.config.ts b/apps/examples/express/src/config/auth.config.ts
@@ -0,0 +1,15 @@
+import GitHub from "@auth/express/providers/github"
+import Google from "@auth/express/providers/google"
+
+export const authConfig = {
+  providers: [
+    GitHub({
+      clientId: process.env.AUTH_GITHUB_ID,
+      clientSecret: process.env.AUTH_GITHUB_SECRET,
+    }),
+    Google({
+      clientId: process.env.AUTH_GOOGLE_ID,
+      clientSecret: process.env.AUTH_GOOGLE_SECRET,
+    }),
+  ],
+}
diff --git a/apps/examples/express/src/errors.ts b/apps/examples/express/src/errors.ts
@@ -0,0 +1,14 @@
+export class HttpError extends Error {
+  status: number
+  constructor(status: number, message: string) {
+    super(message)
+    this.status = status
+  }
+}
+
+export class NotFoundError extends HttpError {
+  constructor(message: string, status = 404) {
+    super(status, message)
+    this.name = "NotFoundError"
+  }
+}
diff --git a/apps/examples/express/src/globals.ts b/apps/examples/express/src/globals.ts
@@ -0,0 +1,5 @@
+import path from "path"
+import { fileURLToPath } from "url"
+
+globalThis.__filename ??= fileURLToPath(import.meta.url)
+globalThis.__dirname ??= path.dirname(globalThis.__filename)
diff --git a/apps/examples/express/src/middleware/auth.middleware.ts b/apps/examples/express/src/middleware/auth.middleware.ts
@@ -0,0 +1,29 @@
+import { getSession } from "@auth/express"
+import { NextFunction, Request, Response } from "express"
+import { authConfig } from "../config/auth.config.js"
+
+export async function authenticatedUser(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) {
+  const session = res.locals.session ?? (await getSession(req, authConfig))
+
+  res.locals.session = session
+
+  if (session) {
+    return next()
+  }
+
+  res.status(400).json({ message: "Not Authenticated" })
+}
+
+export async function currentSession(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) {
+  const session = await getSession(req, authConfig)
+  res.locals.session = session
+  return next()
+}
diff --git a/apps/examples/express/src/middleware/error.middleware.ts b/apps/examples/express/src/middleware/error.middleware.ts
@@ -0,0 +1,24 @@
+import { NextFunction, Request, Response } from "express"
+import { HttpError, NotFoundError } from "../errors.js"
+
+export const errorHandler = (
+  err: HttpError | Error,
+  _req: Request,
+  res: Response,
+  next: NextFunction,
+): void => {
+  // Render the error page
+  res.status(("status" in err && err.status) || 500)
+  res.render("error", {
+    title: "status" in err ? err.status : err.name,
+    message: err.message,
+  })
+}
+
+export const errorNotFoundHandler = (
+  _req: Request,
+  _res: Response,
+  next: NextFunction,
+): void => {
+  next(new NotFoundError("Not Found"))
+}
diff --git a/apps/examples/express/src/server.ts b/apps/examples/express/src/server.ts
@@ -0,0 +1,16 @@
+import "./globals.js"
+import * as dotenv from "dotenv"
+
+// Load environment variables
+dotenv.config({ path: __dirname + "/../.env" })
+
+// Import app after environment variables are set
+const { app } = await import("./app.js")
+
+const port = app.get("port")
+
+const server = app.listen(port, () => {
+  console.log(`Listening on port ${port}`)
+})
+
+export default server
diff --git a/apps/examples/express/tailwind.config.js b/apps/examples/express/tailwind.config.js
diff --git a/apps/examples/express/tsconfig.json b/apps/examples/express/tsconfig.json
diff --git a/apps/examples/express/vercel.json b/apps/examples/express/vercel.json
diff --git a/apps/examples/express/views/error.pug b/apps/examples/express/views/error.pug
diff --git a/apps/examples/express/views/index.pug b/apps/examples/express/views/index.pug
diff --git a/apps/examples/express/views/layout.pug b/apps/examples/express/views/layout.pug
diff --git a/apps/examples/express/views/protected.pug b/apps/examples/express/views/protected.pug
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
