Run develop/watch from workspaces

[ekafyi]

Hi, thank you for this awesome starter.

I wonder what you would recommend for watching/developing all packages at the workspaces level? concurrently? preconstruct?

Of course we can run commands separately at the package level, eg. yarn workspace blog-app dev, just curious about best practices / handy tips out there as I'm a monorepo newbie.

[belgattitude]

Hey @ekafyi

About preconstruct

I wonder what you would recommend for watching/developing all packages at the workspaces level? concurrently? preconstruct?

Nice links, but actually we don't need any build to use / develop in packages. A change in any package will immediately be reflected in your apps (fast-refresh)...

And yes it wasn't that easy before and things like preconstruct made a sense.

If you're wondering how this magic happens, all is the readme. The key points are:

In an app:

1. package.json define your internal package dependencies (prefer using workspace: protocol). more details

   package.json

   {
     "name": "my-app",
     "dependencies": {
       "@your-org/magnificient-poney": "workspace:*",
     },
   }

2. tsconfig.json add your packages path aliases. more details

   Example of tsonfig.json

   {
     "compilerOptions": {
       "baseUrl": "./src",
       "paths": {
         // regular app aliases
         "@/components/*": ["./components/*"],
         // packages aliases, relative to app_directory/baseUrl
   
         "@your-org/magnificent-poney/*": [
           "../../../packages/magnificent-poney/src/*",
         ],
   
         "@your-org/magnificent-poney": [
           "../../../packages/magnificent-poney/src/index",
         ],
       },
     },
   }

3. ǹext.config.js be sure to enable experimental externalDir. more details

   Example of tsonfig.json

   const nextConfig = {
     experimental: {
       externalDir: true,
     },
   };
   export default nextConfig;

You'll see basically point 1 & 2 are a safe way to really ensure your boundaries (deps are explicitely set and mirror each others. I say that because with typescript path aliases you can access pretty much any kind of files)...

Same strategy that NX will inject for you for example.

Point 3 is a new mechanism offered by nextjs, that allows to consider typescript aliases paths without any additional config. If you're on an older NextJs Version, see the readme.

In other words, nextjs app will just use your packages files just like they were belonging to the app and only use what's needed... Last but not least, all caches, typechecks, fast refresh will give you a very good developer experience. (rather than watching, pre building...)

Of course we can run commands separately at the package level, eg. yarn workspace blog-app dev, just curious about best practices / handy tips out there as I'm a monorepo newbie.

I just start with the app I'm working on eg. yarn workspace blog-app dev or cd apps/blog-app; yarn dev (cause of habit I prefer my working directory to be there)

When my work implies a change in a shared package (ie consumed by multiple apps) there's a possibility that my changes would break another app. eg: I change a component prop (a boolean, by a string).

This possibility is most of the time catched by typescript (or unit-test or builds in the ci), it increases a lot my confidence to not creating breaking changes across the apps. (or to see it earlier where I can eventually act on them, choose a different path...).

There's more to say, but it's a bit how I work for a year or two. A lot less mental overhead 😄

I don't really know if it's best practice though.

About concurrently

I wonder what you would recommend for watching/developing all packages at the workspaces level? concurrently? preconstruct?

As seen above, I don't need to watch concurrently. But sometimes I need to run commands concurrently.

As you'll see in the .yarn / yarnrc.yml folder I installed the yarn workspace plugin. It gives a decent taskrunner that allows to run things in parallel for your monorepo.

ie: yarn workspaces foreach -ptv --include '@your-org/*' run typecheck

It's a nice to have and completely integrated experience. See the root package.json to see how I use it.

In older versions of monorepo I was using, I tend to use lerna for this (as a taskrunner)... And sometimes I use npm-run-all. But just for things like unit-test, typechecks, lint, ... (BTW in most CI's running things in parallel is often slower in my experience)

One thing I'd like to add in this example is ultra-runner at some point, it gives a little extra boost. Nice gem...

I'm not sure if it answer your question, but hope it helps.

[ekafyi]

Wow, thanks for the detailed explanation. I didn't know Next could do that! (the externalDir config)

My use case is really for frontend UI components: I'd be developing on the components package (like ui-lib in this starter), and I'd want to run them locally in the apps that consume them (eg. Nextjs web app) to see they work as intended before I build & publish the UI package. I'm not likely to ever need to watch for all packages at once.

I'm going to take the provided Nextjs app sample for a spin, it should be enough for me based on your explanation.

Cheers!

[belgattitude]

Yes I think you'll be happy on this road. And if you have any question let me know.

[belgattitude]

BTW try to avoid css / scss if you can.

Styled systems like emotion are a safer way imo.

Ask if you want more details

[ekafyi]

I have tried it and yes, everything works like ✨ magic 🎩!

This suffices for my use case, thank you!

---

My UI dev workflow, for others browsing this discussion:

(I copied the sample folders and renamed them, but use the original folder names here for clarity)

cd packages/ui-lib && npx -p @storybook/cli sb init to add Storybook to the components lib (personal preference, not necessary or required)

yarn workspace @your-org/ui-lib storybook to run Storybook while developing the components lib (also a personal preference)

yarn workspace blog-app dev to develop the frontend app

Any change in the components library source files is automatically reflected in the app that consumes it as long as they are linked here https://github.com/belgattitude/nextjs-monorepo-example/blob/main/apps/blog-app/tsconfig.json#L13-L14. So no need to watch or run both on dev mode together.

It is possible to develop the components lib by simply running a frontend app that consumes it within the monorepo (eg. blog-app in example above).

Optional DRYness: I created an extra tsconfig.apps.base.json file in the apps dir, extended by frontend apps that consume the same lib dependencies, so I don't have to repeat defining the paths ("@your-org/ui-lib/*": ["../../../packages/ui-lib/src/*"] etc) in each frontend app's tsconfig. This is only necessary if > 2 frontend apps consume the same library dependency.

[belgattitude]

Nice ideas indeed 🔝 , thx for sharing.