Update docs
This commit is contained in:
1 parent
9009a349f3
commit
e8a8adf846
2 files changed
+22
-9
No files matched your search
@@ -2,7 +2,7 @@
|
||||
|
||||
## Overview
|
||||
|
||||
**Dashtab** is a client-side new-tab dashboard built with Ember.js, Vite, and Tailwind CSS. It features widgets (clock, greeting), customizable wallpapers, and third-party integrations (e.g., Discourse).
|
||||
**Dashtab** is a client-side new-tab dashboard distributed as a Manifest V3 browser extension and built with Ember.js, Vite, and Tailwind CSS. It features widgets (clock, greeting), customizable wallpapers, and third-party integrations (e.g., Discourse).
|
||||
|
||||
## Tech Stack
|
||||
|
||||
@@ -12,6 +12,7 @@
|
||||
- **Storage**: `localforage` (IndexedDB / LocalStorage)
|
||||
- **Cryptography**: Web Crypto API & `node-forge`
|
||||
- **Testing**: QUnit, `@ember/test-helpers`, `qunit-dom`, `testem`
|
||||
- **Distribution**: Manifest V3 browser extension (Chrome/Firefox); the web build is dev-only
|
||||
- **Package Manager**: `pnpm`
|
||||
|
||||
## Code Layout
|
||||
@@ -21,14 +22,25 @@
|
||||
- `app/routes/` & `app/templates/`: Route definitions and `.gjs` templates.
|
||||
- `app/styles/`: Application styles and Tailwind entry points.
|
||||
- `doc/`: Protocol notes and integration specifications.
|
||||
- `extension/`: Chrome/Firefox MV3 manifests; `extension/build/` is generated output.
|
||||
- `tests/`: QUnit tests (`tests/integration/` for `.gjs` components, `tests/unit/` for services).
|
||||
|
||||
## Commands
|
||||
|
||||
- `pnpm start`: Start local development server (`http://localhost:4200`).
|
||||
- `pnpm start`: Run the app in the browser for development only (`http://localhost:4200`).
|
||||
- `pnpm test`: Build and run the test suite via Testem.
|
||||
- `pnpm lint`: Run all linters (ESLint, Prettier, stylelint, template-lint).
|
||||
- `pnpm lint:fix`: Auto-fix linting and formatting issues.
|
||||
- `pnpm ext:dev`: Watch-build the Firefox extension and launch it via `web-ext`.
|
||||
- `pnpm ext:build:chrome` / `pnpm ext:build:firefox`: Package the extension.
|
||||
- `pnpm ext:lint`: Lint the packaged extension with `web-ext`.
|
||||
|
||||
## Browser Extension
|
||||
|
||||
Dashtab is a Manifest V3 browser extension that overrides the new tab. It can also run as a plain web app via `pnpm start`, but that path exists only for development convenience. `vite.config.mjs` switches to relative asset paths and copies the target manifest into `extension/build/` when `DASHTAB_EXT=1`, with `DASHTAB_EXT_TARGET` selecting `chrome` or `firefox`. Never edit `extension/build/` by hand.
|
||||
|
||||
- **Manifests**: `extension/manifest.chrome.json` and `extension/manifest.firefox.json`. Extension ids are pinned (Chrome `key`, Firefox `browser_specific_settings.gecko.id`) so `identity.getRedirectURL()` stays stable.
|
||||
- **Auth transport**: `app/auth/transport.js` feature-detects the identity API (`app/utils/extension.js`). The extension uses `identity.launchWebAuthFlow` + `getRedirectURL`; the dev-server build (no identity API) falls back to a full-page redirect to the provider callback. See `doc/extension_auth.md`.
|
||||
|
||||
## Key Conventions
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Integration authorization: web vs. extension
|
||||
# Integration authorization: extension vs. dev server
|
||||
|
||||
Dashtab connects to integrations through a small authorization layer
|
||||
(`app/auth/`):
|
||||
@@ -9,14 +9,15 @@ Dashtab connects to integrations through a small authorization layer
|
||||
without touching the transport.
|
||||
- **Transport** (`app/auth/transport.js`) decides how the browser gets to the
|
||||
provider:
|
||||
- **Web app** → full-page redirect to `${origin}${provider.webCallbackPath}`
|
||||
(e.g. `/auth/discourse/callback`).
|
||||
- **Browser extension** → `identity.getRedirectURL(providerId)` plus
|
||||
`identity.launchWebAuthFlow`, which opens a browser-managed auth window and
|
||||
intercepts the redirect to a browser-owned domain.
|
||||
- **Development server** (no identity API) → full-page redirect to
|
||||
`${origin}${provider.webCallbackPath}` (e.g. `/auth/discourse/callback`).
|
||||
|
||||
The choice is made at runtime by feature-detecting the identity API, so the same
|
||||
build works as a normal site and as an extension.
|
||||
Dashtab ships as a browser extension; the dev-server path exists only for
|
||||
development convenience. The choice is made at runtime by feature-detecting the
|
||||
identity API, so the same build works in both contexts.
|
||||
|
||||
## Forum configuration
|
||||
|
||||
@@ -25,8 +26,8 @@ Discourse only accepts a redirect that matches the
|
||||
`https://api.discourse.org/api/auth_redirect|discourse://auth_redirect`, so an
|
||||
admin must add the redirects Dashtab uses:
|
||||
|
||||
- **Web app** — the deployed origin plus callback path, e.g.
|
||||
`https://dashtab.example.com/auth/discourse/callback`.
|
||||
- **Development server** — the dev origin plus callback path, e.g.
|
||||
`http://localhost:4200/auth/discourse/callback`.
|
||||
- **Chrome / Chromium extension** — `https://<extension-id>.chromiumapp.org/discourse`,
|
||||
or the wildcard `https://*.chromiumapp.org/*`.
|
||||
- **Firefox extension** — `https://<host>.extensions.allizom.org/discourse`
|
||||
|
||||
Reference in new issue
Block a user