69 lines
5.3 KiB
Markdown
69 lines
5.3 KiB
Markdown
---
|
|
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=<path> mode=<dry-run|apply> frontend-origin=<url> allowlist-discord-ids=<csv>"
|
|
---
|
|
|
|
# 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 (`<frontendOrigin>/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:<AUTH_PORT>` 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. |