Thinkmill/monorepo

What folders do we recommend packages go in?

Noviny opened this issue · 7 comments

Noviny commented

Minor decision we should have an opinion on. Start of a conversation around folder structure.

My base assumption for the package-containing folder every monorepo will have:

  • /packages - has packages designed to be consumed by other packages

Some other folders that make sense to me:

  • /apps - has node apps designed to be deployed
  • /websites - has websites designed to be deployed

Other option maybe?

  • /tools or /build - has node or bash or other scripts designed to be run in the repository, but not consumed by other packages.

NB: Assumption is you have 1 or more of these, not that every monorepo should have all 4.

emmatown commented
  • /apps - has node apps designed to be deployed
  • /websites - has websites designed to be deployed

For the projects I've been working on recently(the two more recent repos with design systems), the naming is apps/* is for websites/apps and services/* is for node apps/services.

Also relevant, we've had design systems with the packages at design-system/packages/* and the website at design-system/website.

/tools or /build - has node or bash or other scripts designed to be run in the repository, but not consumed by other packages.

Emotion uses a scripts/* but I think I prefer tools/*.

  • 👍1
elisechant commented

+1 meaningful default naming conventions.

Also, would it be desired to alias these names in a config file like Lerna allows you to?

emmatown commented

Also, would it be desired to alias these names in a config file like Lerna allows you to?

I'm not sure what this, do you have a link to this in Lerna's docs or an example of it?

Noviny commented

Mitchell's name suggestions

Do you have recs on which node apps go in 'apps' and which go in 'services'? That distinction doesn't seem clear.

top level /website folder

Most of our repos do this, but it feels like an antipattern for me. It makes a lot of sense for library monorepos, but is likely harmful for product monorepos so it would be good to consistency it out of existence, and put the website in a thing.

re: scripts v tools

Now you have said /scripts I think I like it better than my suggestions 😛 - I'm more interested in having conventions though so if you have more than weak opinions happy to go with them.

All of this

I propose this as a topic to finalise in the next monorepo meeting based on opinions gathered in this issue.

emmatown commented

Do you have recs on which node apps go in 'apps' and which go in 'services'? That distinction doesn't seem clear.

I think the answer is that apps is for front-end things and services is for back-end things. That of course gets blurry with things like Keystone so I'm not totally sure if it's the ideal way to split things but as an example, in the two client projects I referred to, there is a Next site in /apps and a GraphQL API in /services.

Most of our repos do this, but it feels like an antipattern for me. It makes a lot of sense for library monorepos, but is likely harmful for product monorepos so it would be good to consistency it out of existence, and put the website in a thing.

I think that because it makes sense for library monorepos, we should document it. Also, I think there is a chance that we might want it for product monorepos if there are a bunch of products so that we can have packages for a particular product(e.g. ["/products/*/app", "/products/*/packages/*"]). (Let's not document this now, It's just an idea, this might be something I explore with the client project I'm about to be on a lot more)

Now you have said /scripts I think I like it better than my suggestions 😛 - I'm more interested in having conventions though so if you have more than weak opinions happy to go with them.

I'm happy to go with /scripts.

I propose this as a topic to finalise in the next monorepo meeting based on opinions gathered in this issue.

Agreed.

  • 👍1
Noviny commented

Decision:

- package.json
- packages/* - where packages designed to be consumed by other packages (published OR internal) live
- apps/* - where user-facing apps and websites should live
- services/* - where back-end services should live
- tools/* - where you should put packages intended to be used only within dev loops for your repository
- website/ - the location of the documentation website

For a design system being built alongside an app, you should put the design system packages inside a folder design-system that mirrors the above structure (as needed) except without a package.json in the design-system folder.

  • 👍1
  • 😄1
elisechant commented

I am musing about @mitchellhamilton 's suggestion of products although would it be safe to assume this would only be useful for a case where a product's packages are required within another product?

For example:

products/invoices/app
products/invoices/packages/timesheet-calculator
products/todos/app

where timesheet-calculator is used inside invoices/app as well as todos/app.

This would be as opposed to:

apps/invoices
apps/todos
packages/timesheet-calculator

I think in which case that I prefer the later.