Skip to main content

Running Locally

When developing new Squeeze functionality, you'll want to clone and run the repo locally. This will allow you to see your changes reflected in a local copy of this documentation site, as well as the Dev Playground.

This repo uses pnpm as its package manager and Turbo Repo for its build tooling. Assuming you're running volta, the proper version of pnpm will be automatically installed when using Squeeze.

Setup​

First, clone the repo and install dependencies.

$ git clone https://github.com/curology/design-system.git
$ cd design-system
$ pnpm i

Next, start the development server from the project root. This will build packages/ui-tokens (a dependency of packages/ui-styles-web), then start watching packages/ui-tokens, packages/ui-styles-web, packages/ui-components-web, and apps/docs. Changes to each dependency will be calculated on the fly and live reloaded. Two browser windows will open: one for the documentation site and one for the Dev Playground.

$ pnpm turbo dev

Dev Playground​

Recompiling the documentation site can be slow (3-10 seconds) because it is built on Docusaurus, which uses webpack for its compilation. For a quicker feedback loop, development of new components is faster when done inside of packages/ui-components-web/src/dev/index.tsx. This mini-app compiles using Vite and has build times under 1 second.

Running Tests​

Read more about testing

Building​

It can be useful to build the components and documentation site locally to ensure that everything is working as expected. You can either build individual packages or the entire project, depending on which directory you run the build command from.

pnpm turbo build

Using with the frontend-monorepo​

Although it is preferred to develop components in isolation to ensure they are application-agnostic, it can be useful to use a local copy of Squeeze inside the frontend-monorepo to see your changes reflected before releasing. To do so:

  • Ensure you have frontend-monorepo and design-system cloned locally
  • Run pnpm i inside both repos
  • Run pnpm turbo dev from this project root to start building the components and docs site in watch mode
    • As noted above in Setup, this will open both the docs site and dev playground apps
      • You can close these windows if you aren't using them and the recompilation will continue to run
    • Alternatively, running pnpm turbo dev from inside packages/ui-components-web will build only the components in watch mode, which is slightly faster
  • Run pnpm link /path/to/your-local-git-clone-of-design-system/packages/ui-components-web from inside /path/to/frontend-monorepo/apps/your-app
    • For example, assuming both frontend-monorepo and the design-system repo are in your home directory (~) and you want to link the curology-sign-up app, run pnpm link ~/design-system/packages/ui-components-web from inside ~/frontend-monorepo/apps/curology-sign-up
  • Start your app in dev mode (probably pnpm turbo dev)
  • At this point, both your app and Squeeze will be running in watch mode
    • It can take 10 seconds or more for changes to a component to be reflected in your app
  • Your Next.js app may rebuild more than once when a change is made to Squeeze
    • Next doesn't wait for changes to Squeeze's dist folder to "settle", sometimes causing more than one rebuild
    • You may need to reload your browser to see the change take effect
    • If you're still not seeing design-system changes in your Next.js app like you expect, it's possible that Next.js's caching is preventing the changes from being seen. To fix this, delete the .next directory in your Next.js app directory, and then restart your Next.js app.

When you want to go back to using the currently published version of Squeeze, run pnpm unlink from inside /path/to/frontend-monorepo/apps/your-app. If that doesn't work, discard any changes to pnpm-lock.yaml in frontend-monorepo that may have been caused by the link. Run pnpm i from inside the frontend-monorepo to reinstall the published version of the design system.