{"id":22739827,"url":"https://github.com/auth0-samples/auth0-acul-samples","last_synced_at":"2026-07-13T04:00:27.498Z","repository":{"id":267233525,"uuid":"899358514","full_name":"auth0-samples/auth0-acul-samples","owner":"auth0-samples","description":"Auth0 ACUL React Boilerplate","archived":false,"fork":false,"pushed_at":"2026-06-30T18:10:43.000Z","size":1793,"stargazers_count":19,"open_issues_count":9,"forks_count":33,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-06-30T20:09:59.612Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/auth0-samples.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-06T05:25:05.000Z","updated_at":"2026-05-21T12:43:37.000Z","dependencies_parsed_at":"2025-04-12T20:52:55.384Z","dependency_job_id":"8030f4a1-3658-42a1-9d0e-22b748cd7e39","html_url":"https://github.com/auth0-samples/auth0-acul-samples","commit_stats":null,"previous_names":["auth0/auth0-acul-react-boilerplate","auth0-samples/auth0-acul-samples","auth0-samples/auth0-acul-react-boilerplate"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/auth0-samples/auth0-acul-samples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-acul-samples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-acul-samples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-acul-samples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-acul-samples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auth0-samples","download_url":"https://codeload.github.com/auth0-samples/auth0-acul-samples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0-samples%2Fauth0-acul-samples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35409469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-10T23:06:15.542Z","updated_at":"2026-07-13T04:00:27.487Z","avatar_url":"https://github.com/auth0-samples.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auth0 Advanced Customizations for Universal Login Samples\n\nThis monorepo provides production-ready templates for creating custom Auth0 Advanced Customizations for Universal Login (ACUL) screens. Each sample demonstrates different implementation approaches and SDK integrations while following Auth0's design language and user experience patterns.\n\n**What is ACUL?** Advanced Customizations for Universal Login (ACUL) allows you to build custom, client-rendered versions of Universal Login screens, giving you complete control over your authentication experience. ACUL uses a client/server model where you have full control over the client-side interface while leveraging the security, extensibility, and flexibility of Universal Login's hosted authentication on the server side.\n\n\u003e **⚠️ Important Notes**\n\u003e\n\u003e - **Enterprise Feature**: Requires Enterprise Auth0 plan and verified custom domain\n\n## Available Samples\n\n### [React-JS Sample](./react-js/)\n- **SDK**: Auth0 ACUL JS SDK (`@auth0/auth0-acul-js`)\n- **Screens**: 3 authentication screens\n  - Login (universal login)\n  - Login-ID (identifier-first flow)\n  - Login-Password (password entry)\n- **Tech Stack**: React 19, TypeScript, Vite, Tailwind CSS\n- **Development**: Integrated context inspector for real-time debugging\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg \n        src=\"https://cdn.auth0.com/website/acul-samples/login-id-with-ulx-context.png\" \n        alt=\"Login ID Screen with mock data\"\n        width=\"100%\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cem\u003eLogin-id screen local development with ul-context-inspector\u003c/em\u003e\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg \n        src=\"https://cdn.auth0.com/website/acul-samples/login-id-prod.png\" \n        alt=\"Login ID Screen deployed with ACUL\"\n        width=\"100%\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cem\u003eLogin-id screen production deployment with ACUL\u003c/em\u003e\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n### [React Sample](./react/)\n- **SDK**: Auth0 ACUL React SDK (`@auth0/auth0-acul-react`)\n- **Screens**: 31 authentication screens\n  - **Login \u0026 Authentication (5)**: Login, Login-ID, Login-Password, Login-Passwordless-Email-Code, Login-Passwordless-SMS-OTP\n  - **Signup \u0026 Registration (3)**: Signup, Signup-ID, Signup-Password\n  - **Password Reset (4)**: Reset-Password-Request, Reset-Password-Email, Reset-Password, Reset-Password-Error\n  - **Multi-Factor Authentication (15)**: MFA-Begin-Enroll-Options, MFA-Country-Codes, MFA-Email-Challenge, MFA-Email-List, MFA-Enroll-Result, MFA-Login-Options, MFA-Push-Challenge-Push, MFA-Push-Enrollment-QR, MFA-Push-List, MFA-Push-Welcome, MFA-SMS-Challenge, MFA-SMS-Enrollment, MFA-SMS-List, MFA-WebAuthn-Platform-Challenge, MFA-WebAuthn-Platform-Enrollment\n  - **Passkeys (2)**: Passkey-Enrollment, Passkey-Enrollment-Local\n  - **Identifier Management (2)**: Email-Identifier-Challenge, Phone-Identifier-Challenge\n- **Tech Stack**: React 19, TypeScript, Vite, Tailwind CSS\n- **Development**: Integrated context inspector for real-time debugging\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg \n        src=\"https://cdn.auth0.com/website/acul-samples/signup-with-ulx-context.png\" \n        alt=\"Signup Screen with mock data\"\n        width=\"100%\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cem\u003eSignup screen local development with ul-context-inspector\u003c/em\u003e\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg \n        src=\"https://cdn.auth0.com/website/acul-samples/signup-prod.png\" \n        alt=\"Signup Screen deployed with ACUL\"\n        width=\"100%\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cem\u003eSignup screen production deployment with ACUL\u003c/em\u003e\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Development with ul-context-inspector](#development-with-ul-context-inspector)\n- [Prerequisites](#prerequisites)\n- [Screens](#screens)\n- [Build Structure](#build-structure)\n- [Deployment](#deployment)\n- [Contributing](#contributing)\n- [Documentation](#documentation)\n- [Troubleshooting](#troubleshooting)\n\n\u003ca id=\"quick-start\"\u003e\u003c/a\u003e\n\n## Quick Start\n\n### React-JS Sample (Auth0 ACUL JS SDK)\n\n```bash\n# Navigate to the React-JS sample\ncd react-js\n\n# Install dependencies\nnpm install\n\n# Start development server with context inspector\nnpm run dev  # Opens http://localhost:3000\n```\n\nThe development server includes an integrated context inspector that lets you visualize and edit the Auth0 Universal Login context in real-time, switch between screens, and test different scenarios.\n\n\u003ca id=\"development-with-ul-context-inspector\"\u003e\u003c/a\u003e\n\n## Development with ul-context-inspector\n\n`ul-context-inspector` is a developer panel that simulates Auth0's Universal Login context using local mock data, enabling development without an Enterprise Auth0 tenant.\n\n**How it works:**\n- **Development**: Loads mock JSON from `public/screens/` → No Auth0 connection needed\n- **Production**: Uses real Auth0 context from `window.universal_login_context`\n\n### Creating Local Mocks\n\n1. Add screen mocks in `public/screens/{prompt}/{screen}/`:\n   - `default.json` - Default state\n   - `with-errors.json` - Error state\n\n2. Register in `public/manifest.json`:\n```json\n{\n  \"versions\": [\"v2\", \"v0\"],\n  \"screens\": [\n    {\n      \"login\": {\n        \"login\": {\n          \"path\": \"/screens/login/login\",\n          \"variants\": [\"default\", \"with-errors\"]\n        }\n      }\n    }\n  ]\n}\n```\n\n3. Run `npm run dev` - screens appear in the inspector automatically!\n\n\u003ca id=\"prerequisites\"\u003e\u003c/a\u003e\n\n## Prerequisites\n\n**For Local Development:**\n\n- Node.js version 22+ (`node -v` to check)\n\n**For Production Use:**\n\n- Auth0 tenant with verified custom domain\n- Enterprise Auth0 plan (for ACUL access)\n\n\u003e **Open Source Contributors:** You can explore and contribute to this codebase without needing an Auth0 Enterprise plan using the development context inspector.\n\n\u003cdetails\u003e\n\u003csummary\u003eNeed to install Node.js?\u003c/summary\u003e\n\nWe recommend using NVM (Node Version Manager):\n\n- macOS/Linux: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash`\n- Windows: Install [nvm-windows](https://github.com/coreybutler/nvm-windows)\n\n```bash\nnvm install 22\nnvm use 22\n```\n\n\u003c/details\u003e\n\n### Testing with Real Auth0\n\nOnce you're ready to test with actual Auth0 authentication:\n\n```bash\n# Navigate to the React-JS sample\ncd react-js\n\n# Build and serve assets locally\nnpm run build\nnpx serve dist -p 8080 --cors\n\n# Install Auth0 CLI and configure (Enterprise tenants only)\nnpm install -g @auth0/auth0-cli\nauth0 login\n\n# Configure ACUL with settings file\nauth0 ul customize --rendering-mode advanced --prompt login-id --screen login-id --file ./settings.json\n```\n\n**About settings.json:** This file contains the same ACUL payload configuration as shown in the [Build Structure](#build-structure) section. It defines how Auth0 should load your custom screen assets, including CSS files, JavaScript bundles, and context configuration. The settings.json file structure is identical to the payload you'd use when configuring ACUL programmatically.\n\n\u003e **⚠️ Use development/testing tenants only**\n\n\u003ca id=\"screens\"\u003e\u003c/a\u003e\n\n## Screens\n\nThe main screen implementations are located in:\n\n- **React-JS Sample**: [`react-js/src/screens/`](./react-js/src/screens/) - 3 screens\n- **React Sample**: [`react/src/screens/`](./react/src/screens/) - 31 screens\n\nEach screen is designed to integrate with the [Auth0 ACUL SDK](https://github.com/auth0/universal-login).\n\n\u003ca id=\"build-structure\"\u003e\u003c/a\u003e\n\n## Build Structure\n\n**About manifest.json:** The `manifest.json` file at the project root defines the available templates and screens for the `auth0-cli` tool, enabling developers to scaffold projects with `auth0 acul init` by specifying which files and directories to include for each framework and screen combination.\n\nVite compiles each screen as a separate entry point for optimized loading:\n\n```bash\n# Navigate to the React or React-JS sample\ncd react  # or cd react-js\n\n# Build optimized assets\nnpm run build\n\n# Serve locally for testing\nnpx serve dist -p 8080 --cors\n```\n\n**Output Structure:**\n\n```\ndist/\n├── index.html                           # Main entry point\n└── assets/\n    ├── main.[hash].js                   # Main application bundle\n    ├── shared/\n    │   ├── style.[hash].css             # Global styles (Tailwind + Auth0 theme)\n    │   ├── react-vendor.[hash].js       # React + ReactDOM (~324 kB)\n    │   ├── vendor.[hash].js             # Third-party dependencies (~196 kB)\n    │   └── common.[hash].js             # Shared app code (~87 kB)\n    └── [screen-name]/\n        └── index.[hash].js              # Screen-specific code (0.9-6 kB)\n```\n\n**Bundle Strategy:**\n- **react-vendor**: Contains React and ReactDOM for better caching across deploys\n- **vendor**: Contains all other third-party packages (captcha providers, utilities)\n- **common**: Shared application code (components, hooks, utilities)\n- **Screen bundles**: Only screen-specific logic, optimized for fast loading\n\nScreen-specific bundles can be deployed independently for incremental rollouts.\n\n\u003cdetails\u003e\n\u003csummary\u003eACUL Payload Configuration Example (settings.json)\u003c/summary\u003e\n\nWhen configuring Auth0 ACUL for a specific screen, your settings.json file will reference the built assets:\n\n```json\n{\n  \"rendering_mode\": \"advanced\",\n  \"context_configuration\": [\n    \"branding.settings\",\n    \"branding.themes.default\",\n    \"screen.texts\"\n  ],\n  \"default_head_tags_disabled\": false,\n  \"head_tags\": [\n    {\n      \"tag\": \"base\",\n      \"attributes\": {\n        \"href\": \"https://your-cdn-domain.com/\"\n      }\n    },\n    {\n      \"tag\": \"meta\",\n      \"attributes\": {\n        \"name\": \"viewport\",\n        \"content\": \"width=device-width, initial-scale=1\"\n      }\n    },\n    {\n      \"tag\": \"link\",\n      \"attributes\": {\n        \"rel\": \"stylesheet\",\n        \"href\": \"https://your-cdn-domain.com/assets/shared/style.[hash].css\"\n      }\n    },\n    {\n      \"tag\": \"script\",\n      \"attributes\": {\n        \"src\": \"https://your-cdn-domain.com/assets/main.[hash].js\",\n        \"type\": \"module\"\n      }\n    },\n    {\n      \"tag\": \"script\",\n      \"attributes\": {\n        \"src\": \"https://your-cdn-domain.com/assets/shared/react-vendor.[hash].js\",\n        \"type\": \"module\"\n      }\n    },\n    {\n      \"tag\": \"script\",\n      \"attributes\": {\n        \"src\": \"https://your-cdn-domain.com/assets/shared/vendor.[hash].js\",\n        \"type\": \"module\"\n      }\n    },\n    {\n      \"tag\": \"script\",\n      \"attributes\": {\n        \"src\": \"https://your-cdn-domain.com/assets/shared/common.[hash].js\",\n        \"type\": \"module\"\n      }\n    },\n    {\n      \"tag\": \"script\",\n      \"attributes\": {\n        \"src\": \"https://your-cdn-domain.com/assets/login-id/index.[hash].js\",\n        \"type\": \"module\"\n      }\n    }\n  ]\n}\n```\n\nReference these built assets in your Auth0 ACUL configuration.\n\n\u003c/details\u003e\n\n\u003ca id=\"deployment\"\u003e\u003c/a\u003e\n\n## Deployment\n\nThis repository includes GitHub Actions workflows for automated deployment. See [DEPLOYMENT.md](./react/DEPLOYMENT.md) for complete setup instructions.\n\n\u003cdetails\u003e\n\u003csummary\u003eEnabling Screens for Deployment\u003c/summary\u003e\n\nControl which screens are deployed by modifying [`react/.github/config/deploy_config.yml`](./react/.github/config/deploy_config.yml):\n\n```yaml\ndefault_screen_deployment_status:\n  \"login-id\": true # Enable for deployment\n  \"signup\": false # Disable for deployment\n```\n\n\u003c/details\u003e\n\n\u003ca id=\"contributing\"\u003e\u003c/a\u003e\n\n## Contributing\n\nWe welcome contributions! Here's how you can help:\n\n**Getting Started:**\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature-name`\n3. Make your changes using the development server: `npm run dev`\n4. Test thoroughly: `npm test`\n5. Submit a pull request\n\n**What to Contribute:**\n\n- Bug fixes and improvements\n- Documentation updates\n- Test coverage improvements\n- Component enhancements\n\n**Development Guidelines:**\n\n- Follow the existing code patterns in `react-js/src/screens/` or `react/src/screens/`\n- Use TypeScript for type safety\n- Follow the Auth0 design system principles\n- Include tests for new functionality\n- Use `npm run dev` to start the development server with context inspector\n\n\u003ca id=\"documentation\"\u003e\u003c/a\u003e\n\n## Documentation\n\n- **[Auth0 ACUL Documentation](https://auth0.com/docs/customize/login-pages/advanced-customizations)** - Official ACUL guide\n\n\u003ca id=\"troubleshooting\"\u003e\u003c/a\u003e\n\n## Troubleshooting\n\n### Common Issues\n\n\u003cdetails\u003e\n\u003csummary\u003eScreen not loading or showing blank page\u003c/summary\u003e\n\n**Symptoms:** Browser shows blank page or loading spinner\n**Solutions:**\n\n1. Check browser console for JavaScript errors\n2. Ensure all dependencies installed: `npm install`\n3. Try clearing browser cache and restarting dev server: `npm run dev`\n\u003c/details\u003e\n\n### Getting Help\n\n- **Bug Reports:** [Create an issue](https://github.com/auth0-samples/auth0-acul-samples/issues/new) with reproduction steps\n- **Community Discussion:** [Auth0 Community Forum](https://community.auth0.com/)\n- **Documentation:** [Auth0 ACUL Docs](https://auth0.com/docs/customize/login-pages/advanced-customizations)\n- **Feature Requests:** [Open a discussion](https://github.com/auth0-samples/auth0-acul-samples/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0-samples%2Fauth0-acul-samples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauth0-samples%2Fauth0-acul-samples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0-samples%2Fauth0-acul-samples/lists"}