docs: establish convention for how examples reference the core lib

[Copilot]

Affected Package(s)

• Examples

Related Issue(s)

Motivation

No documented convention existed for how example apps should depend on @forward-software/react-auth. base, reqres, and refresh-token pinned a published version with no local alias, while showcase already used Vite path aliases to the lib source and expo used a Babel alias — with no convention written down anywhere.

Description of Changes

Convention established: examples use a two-layer approach — package.json lists the published version (for standalone/CI use), and the bundler + TypeScript are configured to alias the import to ../../lib/src/index.ts during monorepo development so changes to lib/ are reflected immediately.

• examples/base, reqres, refresh-token — vite.config.ts: added resolve.alias pointing to local lib source (matching showcase)
• examples/base, reqres, refresh-token — tsconfig.json: added compilerOptions.baseUrl and compilerOptions.paths for TypeScript/IDE resolution (baseUrl is required for paths to be applied by tsc)
• examples/README.md (new): central reference covering the two-layer convention for both Vite and Expo setups, how to run each example, and how to add a new one
• CONTRIBUTING.md: added "Contributing examples" section with code snippets for Vite and Expo setups (including the Expo TypeScript paths wildcard mapping); added showcase/ to the examples list
• AGENTS.md: expanded Examples section with a table (including showcase/) and the full convention with snippets for both platforms, including the Expo TypeScript paths mapping

Vite alias pattern (now applied consistently):

// vite.config.ts
resolve: {
  alias: {
    '@forward-software/react-auth': path.resolve(__dirname, '../../lib/src/index.ts'),
  },
},

// tsconfig.json — under "compilerOptions"
{
  "baseUrl": ".",
  "paths": { "@forward-software/react-auth": ["./../../lib/src/index.ts"] }
}

Expo / React Native alias pattern:

// babel.config.js
plugins: [
  ['module-resolver', { alias: { '@forward-software/react-auth': '../../lib' } }],
],

// tsconfig.json — under "compilerOptions"
{
  "paths": { "@forward-software/react-auth/*": ["../../lib/*"] }
}

Breaking Changes

None

How to Test

1. CI Checks: Verify that all automated tests (Vitest) and build steps pass successfully on this PR.
2. Local Verification (Optional):
   • Run pnpm install to install dependencies.
   • Run pnpm --filter <affected-package> test to run tests for the affected package.
   • Run pnpm --filter <affected-package> build to verify the build succeeds.
   • Run pnpm --filter <affected-package> lint to check for linting errors.

Checklist

• My code follows the project's style guidelines
• I have added or updated tests to cover the changes
• I have updated relevant documentation
• All tests are passing locally
• CI checks are passing
• I have reviewed my own code and lock file changes
• I have checked for any potential security implications
• I have verified the changes work as expected
• My commit messages follow Conventional Commits format

Notes for Reviewers

The showcase example already had the correct pattern — this PR makes the other three Vite examples consistent with it and documents the full convention (Vite + Expo) so contributors have a clear reference. The baseUrl: "." addition ensures tsc correctly applies the paths mapping in the three updated examples.

[Copilot]

Pull request overview

Establishes and documents a consistent convention for how example apps in examples/ reference @forward-software/react-auth, aligning the Vite examples with the existing showcase pattern and adding central documentation for contributors.

Changes:

• Add Vite resolve.alias to point @forward-software/react-auth at ../../lib/src/index.ts in the Vite examples (base, reqres, refresh-token).
• Add TypeScript compilerOptions.paths mappings in those examples for editor/TS resolution.
• Add/expand documentation describing the “two-layer” convention and how to run/add examples.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
examples/base/vite.config.ts	Adds Vite alias so the example can import the local core lib source during monorepo dev.
examples/base/tsconfig.json	Adds TS paths mapping for @forward-software/react-auth.
examples/reqres/vite.config.ts	Adds Vite alias to local core lib source.
examples/reqres/tsconfig.json	Adds TS paths mapping for @forward-software/react-auth.
examples/refresh-token/vite.config.ts	Adds Vite alias to local core lib source.
examples/refresh-token/tsconfig.json	Adds TS paths mapping for @forward-software/react-auth.
examples/README.md	New central documentation for examples, including the convention and run instructions.
CONTRIBUTING.md	Adds “Contributing examples” section documenting the convention and listing showcase.
AGENTS.md	Expands the Examples section with a table and documents the convention.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[panz3r]

@copilot can you look into the comments made to the PR and apply appropriate changes?

[Copilot]

@copilot can you look into the comments made to the PR and apply appropriate changes?

Applied all the review feedback in commit f4bab83:

1. baseUrl in tsconfig.json (base, reqres, refresh-token): Added "baseUrl": "." alongside paths in each file.

2. Expo TypeScript paths mapping: Added documentation in examples/README.md, CONTRIBUTING.md, and AGENTS.md showing the wildcard paths entry needed for IDE/tsc resolution in Expo examples (which matches what's already in examples/expo/tsconfig.json):

   { "paths": { "@forward-software/react-auth/*": ["../../lib/*"] } }