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

package/README.md

@@ -31,7 +31,11 @@
     <li>
       <a href="#development">Development</a>
     </li>
+    <li>
+      <a href="#frequently-asked-questions">FAQ</a>
+    </li>
   </ol>
+  </br>
 </details>
 
 ## About
@@ -121,92 +125,69 @@ We use [Storybook](https://storybook.js.org/) for interactive previewing of our
 
 ### Prerequisites
 
-- 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.
+- **Node.js v22 or higher** - Required for development and git hooks
 
-### Component-only work (no CMS needed)
+### Building the Package
 
-```sh
-yarn storybook
-```
-
-Opens Storybook at http://localhost:6006. Iterate on `src/` components and Tailwind plugins without booting the CMS.
+To build the package, run `yarn build` from the package root to create the `dist` folder containing all the compiled assets.
 
-### CMS integration work
+### Local Development with yarn link
 
-The brightspot CMS consumes `@brightspot/ui` from npm. Two workflows for local iteration:
+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.
 
-#### Fast loop: webpack-dev-server (recommended for JS/CSS edits)
+#### Setting up the link
 
-1. Start the CMS in docker as usual (from `brightspot/`):
+1. **In the brightspot-ui package directory:**
 
    ```sh
-   ./gradlew docker
+   yarn link
    ```
 
-2. Start the dev server (from `brightspot-ui/src/legacy/tool-ui/`):
+   This registers the package globally on your system for linking.
+
+2. **In your consuming project directory:**
 
    ```sh
-   yarn server:local
+   yarn link @brightspot/ui
    ```
 
-   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.
+   This creates a symlink from your project's node_modules to the brightspot-ui package.
 
-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.
+   > **_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.
 
-#### Full WAR rebuild (for the modern `src/` surface, or final smoke)
+#### Working with the linked package
 
-`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:
+- 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.
 
-1. Link the package (once per machine, from `brightspot-ui/`):
+#### Removing the link
 
-   ```sh
-   yarn link
-   ```
+When you're done with local development:
 
-2. Consume the link (in `brightspot/cms/tool-ui/`):
+1. **In your consuming project:**
 
    ```sh
-   yarn link @brightspot/ui
+   yarn unlink @brightspot/ui
+   yarn install --force
    ```
 
-3. Edit, then rebuild whichever surface changed:
-
+2. **In the brightspot-ui package directory:**
    ```sh
-   yarn build                              # for src/ edits
-   (cd src/legacy/tool-ui && yarn build)   # for src/legacy/tool-ui/ edits
+   yarn unlink
    ```
 
-4. Rebuild the CMS WAR and roll it into tomcat (from `brightspot/`):
+This restores your project to use the published version from npm.
 
-   ```sh
-   ./gradlew :cms-tool-ui:yarnBuild
-   ./gradlew docker
-   ```
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
 
-5. Smoke at https://localhost/cms/ (apache, port 443).
+## Frequently Asked Questions
 
-### Unlink when done
+Q: How can I see examples of the components and theme?
 
-```sh
-# in brightspot/cms/tool-ui:
-yarn unlink @brightspot/ui && yarn install --force
-
-# in brightspot-ui:
-yarn unlink
-```
+A: See the ["Examples"](#examples) section above.
 
-### Releases
+Q: Can I choose which Brightspot UI plugins my project uses?
 
-`@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.
+A: You have full control over which plugins you include in the tailwind.config file. See the ["using plugins"](#using-plugins) section above.
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>