Skip to content

Commit 7d4b513

Browse files
rax7389rax7389
authored
Merge pull request #255 from auth0/feat/readme-updates-myorg-ea
Update README files to align with other Auth0 SDK repos and v1.0.0 release
2 parents a8b6c32 + 1ada7d0 commit 7d4b513

9 files changed

Lines changed: 719 additions & 601 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Contributing to Auth0 Universal Components
2+
3+
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
4+
5+
- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
6+
- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
7+
8+
## Getting Started
9+
10+
### Prerequisites
11+
12+
- Node.js >= 18
13+
- pnpm (recommended package manager) - Install with `npm install -g pnpm` or see [pnpm.io/installation](https://pnpm.io/installation)
14+
15+
### Installation
16+
17+
1. **Clone the repository:**
18+
19+
```bash
20+
git clone https://github.com/auth0/auth0-ui-components
21+
cd auth0-ui-components
22+
```
23+
24+
2. **Install dependencies:**
25+
26+
```bash
27+
pnpm install
28+
```
29+
30+
3. **Build all packages:**
31+
32+
```bash
33+
pnpm build
34+
```
35+
36+
## Development
37+
38+
### Local Development Workflow
39+
40+
To make and test changes locally:
41+
42+
1. Make your desired changes in any of the packages (e.g., `packages/core` or `packages/react`).
43+
44+
2. Re-build all packages to apply your changes:
45+
46+
```bash
47+
pnpm build
48+
```
49+
50+
3. Navigate to a technology-specific example application in the `examples/` directory (e.g., `examples/react-spa-npm`).
51+
52+
4. Configure the required environment variables in a `.env` file as per the example's README.
53+
54+
5. Start the development server to see your changes in action:
55+
56+
```bash
57+
pnpm dev
58+
```
59+
60+
### Testing
61+
62+
Running tests:
63+
64+
```bash
65+
pnpm test # Run all tests
66+
pnpm test:react # Run React package tests only
67+
pnpm test:core # Run Core package tests only
68+
```
69+
70+
To run a specific test, go to the relevant package folder and run:
71+
72+
```bash
73+
cd packages/react
74+
pnpm test organization-details-edit
75+
```
76+
77+
### Shadcn Local Development
78+
79+
1. Update `registry.json` with your changes.
80+
81+
2. Create a new build based on `registry.json`:
82+
83+
```bash
84+
pnpm build:shadcn
85+
```
86+
87+
3. Open `docs-site` and serve the registry:
88+
89+
```bash
90+
cd docs-site
91+
pnpm install
92+
pnpm dev
93+
```
94+
95+
4. Go to your app (e.g., `react-spa-shadcn`) and update the components:
96+
97+
```bash
98+
npx shadcn@latest add http://localhost:5173/r/my-account/user-mfa-management.json --overwrite
99+
npx shadcn@latest add http://localhost:5173/r/my-organization/organization-details-edit.json --overwrite
100+
# ... other components
101+
```
102+
103+
> [!NOTE]
104+
> The port may differ if other applications are running.
105+
106+
## Monorepo Architecture
107+
108+
This project uses a **monorepo architecture** designed for multi-framework support:
109+
110+
- **`@auth0/universal-components-core`** (`packages/core/`) - Framework-agnostic core with API services, i18n, schemas, and theme utilities
111+
- **`@auth0/universal-components-react`** (`packages/react/`) - React components and hooks with `/spa` and `/rwa` entry points
112+
113+
## Raise an Issue
114+
115+
To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/auth0-ui-components/issues).
116+
117+
## Vulnerability Reporting
118+
119+
Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) details the procedure for disclosing security issues.

‎README.md‎

Lines changed: 70 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,96 @@
1-
# Auth0 Universal Components for Web
1+
![Auth0 Universal Components](https://cdn.auth0.com/website/sdks/banners/universal-components-web.png)
22

3-
A comprehensive library of reusable UI components and utilities for Auth0 integrations, built with modern web technologies and designed for scalability.
3+
Drop-in React components for Auth0 organization management, SSO configuration, and MFA enrollment.
44

5-
## 📖 Documentation
5+
[![npm version](https://img.shields.io/npm/v/@auth0/universal-components-react.svg?style=flat-square)](https://www.npmjs.com/package/@auth0/universal-components-react)
6+
[![license](https://img.shields.io/npm/l/@auth0/universal-components-react.svg?style=flat-square)](https://github.com/auth0/auth0-ui-components/blob/main/LICENSE)
7+
[![downloads](https://img.shields.io/npm/dm/@auth0/universal-components-react.svg?style=flat-square)](https://www.npmjs.com/package/@auth0/universal-components-react)
68

7-
For detailed information on how to use these components and get started with Auth0, please refer to the following resources:
9+
> [!IMPORTANT]
10+
> **Early Access**: This feature is currently in Early Access. To learn more, see [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
811
9-
- **[Auth0 Quickstarts](https://auth0.com/docs/quickstarts)**: Official guides for creating and configuring your application on the Auth0 platform.
10-
- **[Auth0 APIs](https://auth0.com/docs/api)**: Comprehensive documentation for Auth0's APIs.
11-
- **[Component Documentation](https://auth0-ui-components.vercel.app/)**: Live Storybook showcasing all available components, their props, and usage examples.
12-
- **[Examples Folder](https://github.com/auth0/auth0-ui-components/tree/main/examples)**: Practical, hands-on sample applications demonstrating how to integrate and use these components in a real project.
13-
- **[Component Reference](#-component-reference)**: Explore public components available in @auth0/universal-components-react.
12+
📚 [Documentation](#documentation) - 🚀 [Quick Start](#quick-start) - 💬 [Feedback](#feedback)
1413

15-
## Packages Overview
14+
<p align="center">
15+
<img src="https://cdn.auth0.com/website/sdks/banners/SSOProviderCreateComponent.gif" alt="SSO Provider Configuration" width="700">
16+
<br>
17+
<sub>SSO Provider Create Component</sub>
18+
</p>
1619

17-
This project uses a **monorepo architecture** designed for multi-framework support. It is organized into two main types of packages:
18-
19-
- A framework-agnostic `@auth0/universal-components-core` package that contains all the core logic, services, and utilities.
20-
- Framework-specific packages (like `@auth0/universal-components-react`) that provide UI components and hooks for a particular technology. This structure allows for the future addition of packages for other frameworks like Vue or Angular.
21-
22-
### `packages/core/`
23-
24-
**@auth0/universal-components-core** - The foundational package containing core utilities and services.
25-
26-
**What it provides:**
27-
28-
- 📦 **Internal Services**: Handles all API logic for "My Account" and "My Organization" components, using the "My Account" and "My Organization" SDKs.
29-
- 🌐 **Internationalization (i18n)**: Contains all translation files for multi-language support and utils.
30-
- 🛡️ **Schema Validation**: Defines and maintains types for schema validation.
31-
- 🛠️ **Shared Utilities**: Provides shared functions, TypeScript types, and theme management utilities.
32-
33-
### `packages/react/`
34-
35-
**@auth0/universal-components-react** - React-specific UI components and hooks for Auth0 integrations.
36-
37-
**What it provides:**
38-
39-
- ⚛️ **React Components**: Pre-built UI components for Auth0 features (MFA management, user profiles, ,organization management etc.)
40-
- 🎣 **Custom Hooks**: React hooks for component state management and API interactions
41-
- 🎨 **UI Elements**: Beautiful, accessible components built with Radix UI and Tailwind CSS, following shadcn design patterns.
42-
- 🔄 **Providers**: React context providers for managing authentication, theme, and internationalization.
43-
44-
## 🚀 Using the Library
45-
46-
For detailed instructions on how to install and use the components in your project, please refer to the `README.md` file within the specific framework package you are using.
47-
48-
- **[React Usage Guide](./packages/react/README.md)**
49-
50-
## 🛠️ Getting Started (for Contributors)
51-
52-
### Prerequisites
53-
54-
- Node.js >= 18
55-
- PNPM (recommended package manager)
56-
57-
### Installation
58-
59-
1. **Clone the repository:**
60-
61-
```bash
62-
git clone https://github.com/auth0/auth0-ui-components
63-
cd auth0-ui-components
64-
```
65-
66-
2. **Install dependencies:**
67-
68-
```bash
69-
pnpm install
70-
```
71-
72-
3. **Build all packages:**
73-
```bash
74-
pnpm run build
75-
```
76-
77-
### Development
78-
79-
#### Local Development Workflow
80-
81-
To make and test changes locally:
82-
83-
1. Make your desired changes in any of the packages (e.g., `packages/core` or `packages/react`).
84-
2. Re-build all packages to apply your changes:
85-
```bash
86-
pnpm run build
87-
```
88-
3. Navigate to a technology-specific example application in the `examples/` directory (e.g., `examples/react-spa-npm`).
89-
4. Configure the required environment variables in a `.env` file as per the example's `README`.
90-
5. Start the development server to see your changes in action:
91-
```bash
92-
pnpm run dev
93-
```
94-
95-
#### Testing
96-
97-
Running tests:
20+
## Quick Start
9821

9922
```bash
100-
pnpm run test
101-
pnpm run test:react
102-
pnpm run test:core
23+
npm install @auth0/universal-components-react @auth0/auth0-react react-hook-form
10324
```
10425

105-
To run a specific test, go to the relevant package folder and run:
106-
107-
```bash
108-
pnpm run test organization-details-edit
26+
### 1. Wrap Your App with Providers
27+
28+
```tsx
29+
import { Auth0Provider } from '@auth0/auth0-react';
30+
import { Auth0ComponentProvider } from '@auth0/universal-components-react/spa';
31+
import '@auth0/universal-components-react/styles';
32+
33+
function App() {
34+
return (
35+
<Auth0Provider
36+
domain="your-tenant.auth0.com"
37+
clientId="your-client-id"
38+
authorizationParams={{ redirect_uri: window.location.origin }}
39+
interactiveErrorHandler="popup" // Required to handle step-up auth challenges via Universal Login popup
40+
>
41+
<Auth0ComponentProvider themeSettings={{ theme: 'default', mode: 'light' }}>
42+
{/* Your app */}
43+
</Auth0ComponentProvider>
44+
</Auth0Provider>
45+
);
46+
}
10947
```
11048

111-
#### Shadcn Local Development
112-
113-
1. Update `registry.json` with your changes.
49+
### 2. Use a Component
11450

115-
2. Create a new build based on `registry.json`:
51+
```tsx
52+
import { SsoProviderCreate } from '@auth0/universal-components-react/spa';
11653

117-
```bash
118-
pnpm build:shadcn
119-
```
120-
121-
3. Open `docs-site` and serve the registry:
122-
123-
```bash
124-
cd docs-site
125-
pnpm install
126-
pnpm run dev
54+
function SettingsPage() {
55+
return <SsoProviderCreate />;
56+
}
12757
```
12858

129-
4. Go to your app (e.g., `react-spa-shadcn`) and update the components:
130-
131-
```bash
132-
npx shadcn@latest add http://localhost:5173/r/my-account/user-mfa-management.json --overwrite
133-
npx shadcn@latest add http://localhost:5173/r/my-organization/organization-details-edit.json --overwrite
134-
# ... other components
135-
```
59+
[Read the full documentation →](https://auth0.com/docs/get-started/universal-components/universal-components-overview)
13660

137-
_Note: The port may differ if other applications are running._
61+
## Documentation
13862

139-
## 📚 Component Reference
63+
- [Universal Components Overview](https://auth0.com/docs/get-started/universal-components/universal-components-overview) - available components, installation, and configuration
64+
- [Styling Guide](https://auth0.com/docs/get-started/universal-components/universal-components-style) - theming, CSS variables, and dark mode
65+
- [Build a Delegated Admin](https://auth0.com/docs/get-started/universal-components/my-organization/build-delegated-admin) - end-to-end setup guide
66+
- [TypeDoc Reference](https://auth0.github.io/auth0-ui-components/) - TypeDoc-generated source documentation
67+
- [Examples](https://github.com/auth0/auth0-ui-components/tree/main/examples) - sample applications for React SPA, React shadcn, and Next.js
68+
- [Auth0 Docs](https://auth0.com/docs) - explore our docs site and learn more about Auth0
14069

141-
Explore public components available in @auth0/universal-components-react.
70+
## Packages
14271

143-
- [UserMfaManagement](https://auth0.github.io/auth0-ui-components/variables/public-api.UserMFAMgmt.html)
144-
- [DomainTable](https://auth0.github.io/auth0-ui-components/variables/public-api.DomainTable.html)
145-
- [SsoProviderCreate](https://auth0.github.io/auth0-ui-components/variables/public-api.SsoProviderCreate.html)
146-
- [SsoProviderEdit](https://auth0.github.io/auth0-ui-components/variables/public-api.SsoProviderEdit.html)
147-
- [SsoProviderTable](https://auth0.github.io/auth0-ui-components/variables/public-api.SsoProviderTable.html)
148-
- [OrganizationDetailsEdit](https://auth0.github.io/auth0-ui-components/variables/public-api.OrganizationDetailsEdit.html)
72+
| Package | Description |
73+
| ------------------------------------------------------ | ----------------------------------------------------- |
74+
| [@auth0/universal-components-react](./packages/react/) | React components with `/spa` and `/rwa` entry points |
75+
| [@auth0/universal-components-core](./packages/core/) | Framework-agnostic core utilities, services, and i18n |
14976

150-
## 🤝 Contributing
77+
## Feedback
15178

152-
Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs, feature requests, or improvements.
79+
- [Raise an issue](https://github.com/auth0/auth0-ui-components/issues) - Report bugs or request features
80+
- [Contributing Guide](./CONTRIBUTING.md) - Local development setup
81+
- [Vulnerability Reporting](https://auth0.com/responsible-disclosure-policy) - Security issues
15382

154-
## 📜 License
83+
## License
15584

156-
Copyright 2026 Okta, Inc
85+
Copyright 2026 Okta, Inc. Licensed under [Apache License 2.0](LICENSE).
15786

158-
This project is licensed under the [Apache License 2.0](LICENSE). See the [LICENSE](LICENSE) file for details.
87+
---
15988

160-
**Authors**
161-
Okta Inc.
89+
<p align="center">
90+
<picture>
91+
<source media="(prefers-color-scheme: light)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
92+
<source media="(prefers-color-scheme: dark)" srcset="https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png" width="150">
93+
<img alt="Auth0 Logo" src="https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png" width="150">
94+
</picture>
95+
</p>
96+
<p align="center">Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a></p>

0 commit comments

Comments
 (0)