Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sylwia/adds monorepo support section #54

Open
wants to merge 10 commits into
base: main
Choose a base branch
from

Conversation

sylwiavargas
Copy link
Contributor

PR Description

Summary of my changes and explanation of my decisions

  • added monorepo support section: based on the information and examples from @d3lm - please read through and see if it makes sense!
  • added a monorepo question to FAQ: because some folks checked there
  • added troubleshooting switching to the remote branch: because it's a question that appears, based on the info from @KwintenP - please read through and see if it makes sense!

I've placed the monorepo section here but I'm wondering if many users of the classic editor would benefit from this information? Lemme know!

Self-check

Please check all that apply:

  • My code follows the style guidelines of this project
  • I have reviewed my code or content update and edited it to the best of my abilities

Contributors list

Would you like your contribution to be celebrated? Please check all that apply: N/a

  • I would like to be featured on the future contributors list in the README. If so, please tell us:

    • what name you'd like to be shown there?
    • we usually link github profile pic -- is that ok? If not, provide another url:
    • we usually link your github profile but if you have a portfolio page, provide a link:
  • I would like to get a shoutout in the next monthly updates post. If so, please provide your twitter handle (or we will link to your GitHub profile).

⚡️ ⚡️ ⚡️ Thank you for contributing to StackBlitz ⚡️ ⚡️ ⚡️

@stackblitz
Copy link

stackblitz bot commented Oct 15, 2022

Review PR in StackBlitz Codeflow Run & review this pull request in StackBlitz Codeflow.

@netlify
Copy link

netlify bot commented Oct 15, 2022

Deploy Preview for stackblitz-docs ready!

Name Link
🔨 Latest commit a484f75
🔍 Latest deploy log https://app.netlify.com/sites/stackblitz-docs/deploys/636bacc08b8b7900086a2e92
😎 Deploy Preview https://deploy-preview-54--stackblitz-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

Copy link
Contributor

@d3lm d3lm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good @sylwiavargas 👏 Left one minor remark.

docs/codeflow/working-in-codeflow-ide.md Outdated Show resolved Hide resolved
@fvsch
Copy link
Contributor

fvsch commented Oct 17, 2022

I've placed the monorepo section here but I'm wondering if many users of the classic editor would benefit from this information? Lemme know!

I find that the information is a bit hidden, being a sub-section of a page in the Codeflow docs. The link from the FAQ helps a bit, but I wonder if we want it to be more visible and make the monorepo support information a top-level page.

Monorepo support is a frequent question from Enterprise / big companies that are investigating StackBlitz (EE or SaaS).

IMO a natural place would be to have a “Monorepo support” page in the WebContainers section.

But if we want to prioritize people reading through the Codeflow docs, and want to pre-empt their questions as they read, the current placement might make sense.

@sylwiavargas
Copy link
Contributor Author

IMO a natural place would be to have a “Monorepo support” page in the WebContainers section.

That was another option I was considering - thank you! I'll transclude it in both places:

  • a page in WebContainers section
  • a subsection where it currently is
  • and an FAQ link

wdyt, @fvsch ?

@KwintenP
Copy link
Contributor

@sylwiavargas FYI, I'm working on the solution where this is not needed anymore. It actually doesn't seem to be super difficult to get working but I don't want to count my chickens just yet.

@sylwiavargas
Copy link
Contributor Author

Hi @fvsch! I've transcluded the monorepo support page for WebContainers. Could you have a look please?

Copy link
Contributor

@fvsch fvsch left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I don't like having the same content duplicated on 2 pages. But I won't block this approach if we think it's the right one.


## Running monorepos in Codeflow IDE

Codeflow IDE supports workspaces. Follow a walkthrough below to get your monorepo running in Codeflow. <!-- @include: ../parts/monorepo-support.md -->
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not fond of having a large content fragment that we include in several places, to be honest. I like having a single URL where content leaves. Might be better for SEO (avoids the risk of a search engine classing a page as duplicate content and removing it from its index), and for search (you don't get two competing results for the same information).

docs/codeflow/working-in-codeflow-ide.md Outdated Show resolved Hide resolved

Check [npm documentation](https://docs.npmjs.com/cli/v7/using-npm/workspaces) for more information or [this npm-based monorepo demo](https://stackblitz.com/edit/node-4cygsf?file=README.md) for reference.

### pnpm
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having those entries as H3s works when including them in the working-in-codeflow-ide.md page, but not when including them in the dedicated monorepo-support.md page. In that second page, I would expect to see an outline but with H3s we're not getting one:

Screen Shot 2022-11-09 at 14 17 39

docs/parts/monorepo-support.md Outdated Show resolved Hide resolved
```
"workspaces": [
"packages/*"
],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this page, some of our examples of fragments from package.json use a final comma, and some don't. Can we harmonize it?

My vote would be for no trailing comma, because:

  • it looks a bit distracting;
  • if you copy this config to add it at the end of your package.json, you have to add a comma before and remove the final comma.

It's hard to predict where users will need to add commas exactly to have valid JSON, so I'd rather let users be responsible for that. But I’m fine with always including the trailing comma if we think that's better (as long as we're consistent).

docs/parts/monorepo-support.md Outdated Show resolved Hide resolved
docs/parts/monorepo-support.md Outdated Show resolved Hide resolved
Check [pnpm documentation](https://pnpm.io/workspaces) for more information or [this pnpm-based monorepo demo](https://stackblitz.com/edit/node-gw1rvh?file=README.md) for reference.


### Yarn
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we specify that we support Yarn v1 only?

I'm not sure if Yarn Berry (v2+) workspaces are exactly the same or different.


The `workspace:` protocol ensures the correct package from the workspace is used. However, this is not required because, by default, pnpm will link packages from the workspace if the available packages match the declared ranges.

Check [pnpm documentation](https://pnpm.io/workspaces) for more information or [this pnpm-based monorepo demo](https://stackblitz.com/edit/node-gw1rvh?file=README.md) for reference.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally the two example projects we link from this page could have:

  • a more distinctive slug (for instance sb-monorepo-example-pnpm and sb-monorepo-example-npm)
  • nice titles and descriptions

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants