--- name: discord-oauth-vue3-vite description: "Use when scaffolding Discord OAuth into a Vue 3 + Vite app with a server bundle under src/server, PKCE, session handling, and route protection." argument-hint: "project-root= mode= frontend-origin= allowlist-discord-ids=" --- # Discord OAuth Vue 3 + Vite Use this skill when you want a portable, repeatable Discord OAuth setup for a Vue 3 + Vite app and you want the server-side auth bundle kept under `src/server/` instead of a standalone `scripts/` service. ## Procedure ### Server bundle 1. Confirm the target project root and review the generated server bundle path, which defaults to `src/server/discord-oauth`. 2. Confirm the user-owned prerequisites: a Discord application, the authorized redirect URI, client ID, client secret, and any Discord user IDs that should be allowlisted. 3. Run `resources/scripts/scaffold-discord-oauth-vue3-vite.sh` in `--mode dry-run` first when the shared resources repo is available; if the script path is not available in the current workspace, continue with the manual scaffold path instead of stopping. 4. Let the scaffold create the auth bundle under `src/server/` with PKCE state handling, Discord token exchange, profile fetch, allowlist checks, refresh-session rotation, and logout cleanup. 5. Copy the generated `clients.example.json` to `clients.json` and fill in the Discord client credentials and frontend origin values. 6. Set `AUTH_PORT`, `JWT_SECRET`, and the other auth env vars locally. Align the Discord redirect URI with the app callback route (`/oauth/callback?provider=discord`). ### Client-side wiring 7. Create `useAuth.js` as a module-level singleton composable under `src/client/src/composables/` using the reference template at `resources/templates/discord-oauth-vue3-vite/src/client/composables/useAuth.js`. The singleton exposes `user`, `features`, `isLoading`, `isLoggedIn`, `checkSession()`, `login()`, `logout()`, and `setSession()`. 8. Create `DiscordAuthWidget` as an organism under `src/client/src/components/organisms/` with a colocated SCSS file and a stories stub, using the reference templates at `resources/templates/discord-oauth-vue3-vite/src/client/components/organisms/`. Update the SCSS `@use` paths to match the target project's style foundation before placing. Both the `.vue` and `.scss` must exist; the stories stub must export `LoggedOut` and `LoggedIn`. 9. Create `OAuthCallbackPage.vue` under `src/client/src/pages/` using the reference template at `resources/templates/discord-oauth-vue3-vite/src/client/pages/OAuthCallbackPage.vue`. Register it on the `/oauth/callback` route with no `meta.requiresAuth` guard. 10. Add a `beforeEach` router guard: call `checkSession()` before any route with `meta.requiresAuth: true` and redirect to `/` if `isLoggedIn` is false. Mark protected routes with `meta: { requiresAuth: true }`. 11. Add a Vite dev proxy entry for `/api/auth` pointing to `http://localhost:` in `vite.config.js`. ### Runtime and validation 12. Either run the auth server as its own Node process (add an `auth:dev` script: `node src/server/discord-oauth/server.js`) or mount it into an existing backend entrypoint. 13. Validate the flow: start login, complete the callback, check the session endpoint, refresh the session, and log out. Confirm the allowlist rejects an unapproved Discord account. ## Outputs **Server bundle** (scaffold script writes these): - `src/server/discord-oauth/server.js` - `src/server/discord-oauth/config.js` - `src/server/discord-oauth/sessionStore.js` - `src/server/discord-oauth/allowlist.js` - `src/server/discord-oauth/providers/discord.js` - `src/server/discord-oauth/lib/oauth/pkce.js` - `src/server/discord-oauth/lib/oauth/providers.js` - `src/server/discord-oauth/clients.example.json` - `src/server/discord-oauth/README.md` **Client files** (placed from reference templates; adapt paths per project): - `src/client/src/composables/useAuth.js` - `src/client/src/components/organisms/DiscordAuthWidget.vue` - `src/client/src/components/organisms/DiscordAuthWidget.scss` - `src/client/src/components/organisms/DiscordAuthWidget.stories.js` - `src/client/src/pages/OAuthCallbackPage.vue` ## Do Not Use - Do not use this workflow when the project does not have a Node-side runtime path for auth code under `src/server/`. - Do not use this workflow when the project uses a hosted auth provider or a managed backend where Discord auth should not live in the repo. - Do not store secrets in the generated files. ## Notes - This workflow follows the proven pattern: origin-specific client config, PKCE, Discord code exchange, allowlist gating, refresh-token rotation, and cookie cleanup. - Client template files live in `resources/templates/discord-oauth-vue3-vite/src/client/` and are reference-only. Adapt component paths and SCSS `@use` imports to match the target project's conventions before placing them. - Projects using atomic design require colocated SCSS and a stories stub for every organism; the `DiscordAuthWidget` templates satisfy this by default. - Keep the generated bundle generic to Vue 3 + Vite so the same path can be reused in other apps. - If the project does not already have a server entrypoint, add an `auth:dev` script that runs `node src/server/discord-oauth/server.js`, then configure Vite to proxy `/api/auth` to that port.