[docs] Move dependencies/scripts from root into workspace #16640
Conversation
| "docs:dev": "rimraf node_modules/.cache/babel-loader && cross-env BABEL_ENV=docs-development node docs/src/server.js", | ||
| "docs:export": "rimraf docs/export && next export -o docs/export && yarn docs:build-sw && cp -r docs/static/. docs/export", | ||
| "docs:icons": "rimraf static/icons/* && node ./docs/scripts/buildIcons.js", | ||
| "docs:api": "rimraf ./docs/pages/api && cross-env BABEL_ENV=test babel-node ./docs/scripts/buildApi.js ./packages/material-ui/src ./docs/pages/api && cross-env BABEL_ENV=test babel-node ./docs/scripts/buildApi.js ./packages/material-ui-lab/src ./docs/pages/api", |
There was a problem hiding this comment.
These need to stay for now since they abuse the babel test environment.
eps1lon
changed the title
eps1lon
changed the title
eps1lon
force-pushed
the
docs/workspace-azure
branch
from
45217d5 to
4944bb7
Compare
Details of bundle changes.Comparing: b3218e7...6366654
|
There was a problem hiding this comment.
Well done :). I'm really happy to see the documentation pages centralized.
I have a nip note regarding this folder: /docs/netlify.
Half of the files in this folder are not directly related to Netlify. What do you think of renaming the folder /docs/cdn?
reduced top level scripts with yarn v2 (current script entries in package.json will become obsolete)
Does it refer to #15497? +1 for consolidating all the scripts under a single place, a single place that people can discover, browse and learn more about.
I often find myself running npm run to see what the available command are on a project (even with Material-UI because I have poor memory retention). I'm not aware of a similar command with yarn. I wish these CI tools embraced the scripts documentation problem natively (it's the problem we are trying to solve, right?).
Sounds fine. Was just the first thing to cross my mind. Do we need the favicon duplication? Currently we have one under
Yeah this is more of a concern for #15497. The scripts format just doesn't scale beyond 20 or 30 scripts and multiple workspaces. But at least you have |
eps1lon
force-pushed
the
docs/workspace-azure
branch
from
4944bb7 to
7e6fac3
Compare
|
We could add a root script for it 😄: |
@eps1lon We need the favicon at the root level for production. We need the favicon at the /static folder to remove 404 errors in development mode (browsers aggressive favicon fetching). This is a quick and dirty fix. I think that a proper solution would be to keep the favicon at the cdn folder but to add a static middleware in our the development express server to serve the files in the /cdn folder. Does it worth the effort? diff --git a/pages/_document.js b/pages/_document.js
index 76beb8ee0..bfa1cd263 100644
--- a/pages/_document.js
+++ b/pages/_document.js
@@ -49,7 +49,7 @@ class MyDocument extends Document {
<link rel="manifest" href="/static/manifest.json" />
{/* PWA primary color */}
<meta name="theme-color" content={themeColor} />
- <link rel="shortcut icon" href="/static/favicon.ico" />
+ <link rel="shortcut icon" href="/favicon.ico" />
{/* SEO */}
<link
rel="canonical"
Oh yes, it does, at least with yarn v1.17.0 😍.
I'm curious to understand what you mean by it doesn't scale :) |
For a couple of scripts it's usually pretty obvious what their purpose is or what they do (build, test, lint, format etc). Once the workspace grows (in size and usage) more esoteric scripts get added. Explaining every script requires an additional section in CONTRIBUTING that can easily become out of date. So with more scripts documentation gets worse which can't be inlined into package.json. The other issue is that you need to consider cross environment concerns. It's easy to be lazy and put in the occasional And then there's readability of a script. Add 2 env variables, 3 cli flags and maybe pipe the exit code and readability as well as deuggability is usually gone at that point. |
eps1lon
force-pushed
the
docs/workspace-azure
branch
from
7e6fac3 to
cd8cba8
Compare
eps1lon
force-pushed
the
docs/workspace-azure
branch
from
cd8cba8 to
105afb8
Compare
Nah that's fine. This almost never changes and we never had inconsistent icons. Just wanted to make sure this actually serves a purpose. Fine by me for merging. Any concerns remaining? |
Can we edit the sources and see the changes live in the dev documentation? I can't make HMR work on my env with the core components. Otherwise, it's all 👍 for me. I think that I would personally slightly prefer having 100 scripts in the root package.json than 20 spread among 5 different files. That's my bias toward preferring monoliths. But I'm happy to try it the other way :). |
Oh come on now. Why do you need workspaces then. We're again at a point where you argue for arguments sake. |
Will look into it. |
I "knew" I was going to trigger this response :). Anytime I see an important point where our vision might not align or an important point where I feel we haven't explored the alternatives, I will dive into it. I will try to push the exploration of the pros and cons forward. It's mostly driven by curiosity. Why would somebody else think differently? Why could have I missed? It's definitely not the first time nor the last time I do it. Don't see it as an ego war, a.k.a., who is right, but see it as a best option exploration. I wish we didn't need workspaces in the first place. But unfortunately, we had to introduce them to solve npm code delivery issues. It probably started with the icon package, a big package, slow to download that we rarely release. And it grew from there, lab, system, styles, utils, and types. Correct me if you think otherwise, I think that we should aim for 1. a monolith, so we can minimize the degrees of freedoms (at the cost of marginal suboptimizations). 2. and that we should aim at maximizing code removal potential (isolation). I think that the two can happen together in most cases. End of the (). |
eps1lon
force-pushed
the
docs/workspace-azure
branch
from
b36cc7b to
6366654
Compare
|
Well done 👍 |
Based of #16092 (azure didn't pick it up)
BREAKING
This is just a refactor so don't expect immediate features. The features this will enable are:
Refactoring improvements:
I hope that the new layout will make it easier to debug why we can't esmodules in our docs.
Test plan:
scripts
apibuldbuild-swdeploydevexporticonssize-whystarti18ntypescripttypescript:checktypescript:formattedsuccessful deploys over time