docs(legacy)!: finalize v1.0.0 and guide users to upcoming monorepo (#55)

* feat: update to latest version of js sdk, docs and announcement

* chore: remove reference to shared utilities in migration guide

* docs: update SDK integration example in changelog

Author: amberkamboj77

.gitignore

@@ -30,9 +30,6 @@ coverage/
 # Development tools
 .husky/
 
-# Documentation
-docs/
-
 # Operating system files
 .DS_Store
 .DS_Store?

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.  
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),  
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [v1.0.0] - 2025-10-27
+
+### Added
+
+- Initial release of the Auth0 ACUL sample app.
+- Includes a single auth0-acul-js SDK integration example.
+- Basic documentation and setup instructions.
+
+### Deprecated
+
+- This version is now superseded by the upcoming **v2.0.0 (monorepo)** release.
+
+---
+
+## [Unreleased]
+
+### Planned
+
+- Merge of the `monorepo-sample` branch into `main`
+- Addition of multiple framework samples (React, JS/TS)
+- Introduction of automated changelog and release tagging via GitHub Actions

README.md

@@ -1,5 +1,19 @@
 # Auth0 Advanced Customizations for Universal Login Template
 
+> ⚠️ **Important Notice (Oct 2025):**  
+> This repository is being restructured into a **monorepo** that will host multiple framework-specific samples (React SDK, JS/TS SDK, etc.).  
+> If you’re looking for the **previous single-sample version**, please use the **v1.x** tag:
+>
+> ```bash
+> git clone https://github.com/auth0-samples/auth0-acul-samples.git
+> cd auth0-acul-samples
+> git checkout v1.0.0
+> ```
+>
+> The new monorepo version will be released on **Oct 31, 2025**.
+
+---
+
 This project provides a production-ready template for creating custom Auth0 Advanced Customizations for Universal Login (ACUL) screens using React, TypeScript, and Tailwind CSS. The template follows the same design language and user experience patterns as Auth0's Universal Login screens while integrating with the [Auth0 ACUL SDK](https://github.com/auth0/universal-login) to provide seamless authentication functionality.
 
 **What is ACUL?** Advanced Customizations for Universal Login (ACUL) is an Early Access capability that allows you to build custom, client-rendered versions of Universal Login screens, giving you control over every pixel of 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.
@@ -296,3 +310,23 @@ We welcome contributions! Here's how you can help:
 - **Community Discussion:** [Auth0 Community Forum](https://community.auth0.com/)
 - **Documentation:** [Auth0 ACUL Docs](https://auth0.com/docs/customize/login-pages/advanced-customizations)
 - **Feature Requests:** [Open a discussion](https://github.com/auth0-samples/auth0-acul-samples/discussions)
+
+---
+
+## Migration and Legacy Information
+
+If your project depends on the old structure, you can continue using the **v1.x** releases.
+
+See the [Migration Guide](./docs/migration-guide.md) for details on:
+
+- What has changed in the monorepo structure
+- How to migrate
+- How to stay on the legacy version safely
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a full list of changes between releases.
+
+---

docs/migration-plan.md

@@ -0,0 +1,53 @@
+# Migration Guide — v1.x → v2.0.0 (Monorepo)
+
+## Overview
+
+Starting from **v2.0.0**, this repository has been restructured into a **monorepo**.  
+Each framework-specific sample now lives under its own folder at the repository root.
+
+```
+/react/           → React SDK sample
+/react-js/        → JS/TS SDK sample
+/docs/            → Documentation and migration guides
+```
+
+---
+
+## Why This Change?
+
+- To simplify maintaining multiple samples in one repository
+- To reduce duplication and standardize setup/configuration
+- To enable automated releases and changelogs
+- To support CI/CD pipelines for sample validation
+
+---
+
+## How to Stay on the Old Version
+
+If your existing projects depend on the old structure:
+
+```bash
+git checkout v1.0.0
+```
+
+That version will remain available indefinitely as the last **v1.x (legacy)** release.
+
+---
+
+## Breaking Changes
+
+| Area             | Change                                                 | Notes                                         |
+| ---------------- | ------------------------------------------------------ | --------------------------------------------- |
+| Folder structure | Sample code moved into framework-specific folders      | Adjust your paths and setup steps accordingly |
+| Scripts          | Each sample now has its own `package.json` and scripts | Run commands per sample directory             |
+| Dependencies     | Version bumps and reorganized modules                  | Check each sample’s `package.json`            |
+| Documentation    | Moved into `/docs/`                                    | Updated setup and run instructions            |
+
+---
+
+## Next Steps
+
+- Explore the new monorepo structure (`v2.0.0+`)
+- Read each sample’s local `README.md` for setup
+- Refer to the root [CHANGELOG.md](../CHANGELOG.md) for detailed updates
+- Open issues or PRs if you encounter migration problems

jest.config.cjs

@@ -11,6 +11,6 @@ module.exports = {
     '^@/(.*)$': '<rootDir>/src/$1',
   },
   // Allow transforming ESM modules from node_modules.
-  transformIgnorePatterns: ['/node_modules/(?!@auth0/auth0-acul-js/)'],
+  transformIgnorePatterns: ['/node_modules/(?!(friendly-challenge|@auth0/auth0-acul-js)/)'],
   setupFilesAfterEnv: ['<rootDir>/src/test/setup.ts'],
 };