@brightspot/ui 3.0.1-cms-ui-migration.2 → 3.0.1-cms-ui-migration.3

package/README.md

@@ -31,11 +31,7 @@
     <li>
       <a href="#development">Development</a>
     </li>
-    <li>
-      <a href="#frequently-asked-questions">FAQ</a>
-    </li>
   </ol>
-  </br>
 </details>
 
 ## About
@@ -125,69 +121,92 @@ We use [Storybook](https://storybook.js.org/) for interactive previewing of our
 
 ### Prerequisites
 
-- **Node.js v22 or higher** - Required for development and git hooks
+- Node.js v22+
+- Yarn 1 (classic)
+
+### Layout
+
+This repo ships two surfaces inside one published `@brightspot/ui` npm package:
+
+- `src/` — the modern design system (web components, Tailwind plugins, presets). Built by `yarn build` into `dist/`.
+- `src/legacy/tool-ui/` — the brightspot CMS frontend (JS, CSS, webpack, tests). Has its own `package.json`. Built by `(cd src/legacy/tool-ui && yarn build)` into `src/legacy/tool-ui/src/main/webapp/dist/`.
+
+The publish flow (`yarn prepack`) builds both.
 
-### Building the Package
+### Component-only work (no CMS needed)
 
-To build the package, run `yarn build` from the package root to create the `dist` folder containing all the compiled assets.
+```sh
+yarn storybook
+```
+
+Opens Storybook at http://localhost:6006. Iterate on `src/` components and Tailwind plugins without booting the CMS.
 
-### Local Development with yarn link
+### CMS integration work
 
-For local development and testing, use `yarn link` to create a symlink between this package and your consuming project. This approach provides real-time updates as you make changes to the brightspot-ui source code.
+The brightspot CMS consumes `@brightspot/ui` from npm. Two workflows for local iteration:
 
-#### Setting up the link
+#### Fast loop: webpack-dev-server (recommended for JS/CSS edits)
 
-1. **In the brightspot-ui package directory:**
+1. Start the CMS in docker as usual (from `brightspot/`):
 
    ```sh
-   yarn link
+   ./gradlew docker
    ```
 
-   This registers the package globally on your system for linking.
-
-2. **In your consuming project directory:**
+2. Start the dev server (from `brightspot-ui/src/legacy/tool-ui/`):
 
    ```sh
-   yarn link @brightspot/ui
+   yarn server:local
    ```
 
-   This creates a symlink from your project's node_modules to the brightspot-ui package.
+   Proxies to `localhost` (or `~/.brightspot/local-url` if set), serves freshly compiled assets at `/cms/dist/`, and injects `x-brightspot-dev: 1` on proxied requests so the CMS returns unhashed asset paths.
 
-   > **_Note_** Be sure this is done in the directory where the `package.json` file resides for the CMS UI. Currently that is at `/cms/tool-ui`. You will need to validate your changes via your locally running Brightspot Tool UI Webpack server. It will not work directly over Docker's Tomcat.
+3. Open the CMS at the dev-server URL (https://localhost:8080/cms/) instead of the docker URL. Edit files in `src/legacy/tool-ui/src/`; changes hot-reload in the browser.
 
-#### Working with the linked package
+#### Full WAR rebuild (for the modern `src/` surface, or final smoke)
 
-- From within _**this**_ module, run `yarn build` to ensure the `dist` folder is updated with your changes.
-- From within tool-ui of Brightspot CMS, restart your local webpack server (`yarn server:local`) to pickup the linked brightspot ui module changes.
+`yarn server:local` only serves `src/legacy/tool-ui/`. For edits to the modern surface in `src/`, or to validate against the actual WAR build:
 
-#### Removing the link
+1. Link the package (once per machine, from `brightspot-ui/`):
 
-When you're done with local development:
+   ```sh
+   yarn link
+   ```
 
-1. **In your consuming project:**
+2. Consume the link (in `brightspot/cms/tool-ui/`):
 
    ```sh
-   yarn unlink @brightspot/ui
-   yarn install --force
+   yarn link @brightspot/ui
    ```
 
-2. **In the brightspot-ui package directory:**
+3. Edit, then rebuild whichever surface changed:
+
    ```sh
-   yarn unlink
+   yarn build                              # for src/ edits
+   (cd src/legacy/tool-ui && yarn build)   # for src/legacy/tool-ui/ edits
    ```
 
-This restores your project to use the published version from npm.
+4. Rebuild the CMS WAR and roll it into tomcat (from `brightspot/`):
 
-<p align="right">(<a href="#readme-top">back to top</a>)</p>
+   ```sh
+   ./gradlew :cms-tool-ui:yarnBuild
+   ./gradlew docker
+   ```
 
-## Frequently Asked Questions
+5. Smoke at https://localhost/cms/ (apache, port 443).
 
-Q: How can I see examples of the components and theme?
+### Unlink when done
 
-A: See the ["Examples"](#examples) section above.
+```sh
+# in brightspot/cms/tool-ui:
+yarn unlink @brightspot/ui && yarn install --force
+
+# in brightspot-ui:
+yarn unlink
+```
 
-Q: Can I choose which Brightspot UI plugins my project uses?
+### Releases
 
-A: You have full control over which plugins you include in the tailwind.config file. See the ["using plugins"](#using-plugins) section above.
+`@brightspot/ui` ships via release-please. For migration-track prereleases (`-cms-ui-migration.N`), bump the version, publish to npm, then update the consumer pin in `brightspot/cms/tool-ui/package.json` and rerun `yarn install` there.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>