How asgardeo/javascript works
Project type and purpose
• This is a large monorepo hosting Asgardeo’s JavaScript SDKs: framework-agnostic core libraries, browser and Node/Express SDKs, and framework bindings for React, Next.js, Nuxt, Vue and routing libraries (React Router, Tanstack Router).
• Its purpose is to let front-end and back-end applications integrate with the Asgardeo identity service via OIDC/OAuth2 flows, theming, i18n and session management.
File‐structure / architectural patterns
• Top level
• docs/ – static documentation and images for gh-pages
• packages/ – one folder per SDK package
• .github/workflows – CI and publish pipelines
• nx.json, pnpm-workspace.yaml – monorepo workspace config
• packages/ contains:
• __legacy__ subfolders for previous major versions
• src/ with framework-specific entry-points, API wrappers, context providers, hooks, middleware, models and utils
• tests and tsconfig/build configs per package
• Shared sub-modules
• core (authentication client, branding, i18n)
• javascript (core SDK with API, constants, errors, models, utils)
• i18n (translation bundles)
• Framework-specific packages depend on core/javascript/i18n:
• @asgardeo/browser, @asgardeo/node, @asgardeo/express
• @asgardeo/react, @asgardeo/nextjs, @asgardeo/nuxt, @asgardeo/vue
• @asgardeo/react-router, @asgardeo/tanstack-router
Key README insights
• Lists each published package and its intended environment.
• Points to QuickStarts for React and Next.js, implying client apps use those SDKs.
• Emphasizes modularity, extensibility and common contribution workflows.
a. Main Components
• Monorepo root (workspace tooling, CI/CD, docs site)
• Shared libraries: Core, JavaScript SDK, i18n
• Environment SDKs: Browser, Node, Express
• Framework bindings: React, Next.js, Nuxt, Vue, React-Router, Tanstack Router
• External Asgardeo Identity Service (OIDC/OAuth2)
• Consumer applications (sample React, Next.js, Vue, Node/Express servers)
b. Interactions
• CI/CD (GitHub Actions) triggers lint, test, build, changelog aggregation, publish to npm, docs deploy to gh-pages
• Each package imports common core modules; framework bindings import JavaScript SDK + core + i18n
• Apps depend on framework SDK packages to call Asgardeo endpoints for sign-in, token exchange, session management
• SDKs call out to Asgardeo’s REST/OIDC endpoints and return tokens → apps use tokens to call protected APIs
c. Architectural patterns
• Monorepo with workspace tool (pnpm + Nx) for cross-package versioning and build orchestration
• Layered library design: core → language SDK → environment SDK → framework SDK → application
• Legacy folder pattern indicates migration path/versioning
• CI pipelines implementing changeset-based release (changeset config, workflows)
d. Key technologies
• TypeScript for all source
• Rollup / esbuild for bundling
• Vitest / Jest for testing
• GitHub Actions for CI/CD and npm publishing
• pnpm + nx for workspace management