Skip to content

Sylwia/adds monorepo support section #54

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.

Sign up for GitHub

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

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
+129 −41
Open

Sylwia/adds monorepo support section #54

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bfb68cb
adds a monorepo support info
sylwiavargas Oct 15, 2022
a2ad4f8
adds switching to remote branch troubleshooting
sylwiavargas Oct 15, 2022
e30fc7f
adds examples
sylwiavargas Oct 17, 2022
ed13d4b
Merge branch 'main' into sylwia/adds-monorepo-support-section
sylwiavargas Oct 17, 2022
9a9b6a2
Merge branch 'main' into sylwia/adds-monorepo-support-section
sylwiavargas Nov 7, 2022
b3f1a74
adds monorepo support page in the docs
sylwiavargas Nov 7, 2022
9aba289
Update docs/codeflow/working-in-codeflow-ide.md
sylwiavargas Nov 9, 2022
480cd22
Update docs/parts/monorepo-support.md
sylwiavargas Nov 9, 2022
ea80e3b
Update docs/parts/monorepo-support.md
sylwiavargas Nov 9, 2022
a484f75
Update docs/parts/monorepo-support.md
sylwiavargas Nov 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/codeflow/codeflow-faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@ Yes. Private repositories are available for free during beta through 2022. Start

At this moment we only support GitHub.com repositories.

### Can I run monorepos? Does Codeflow support workspaces?

Yes! Please see the walkthrough at [the "Working in Codeflow IDE" page](/codeflow/working-in-codeflow-ide#running-monorepos-in-codeflow-ide).

### Which files can be opened in Web Publisher?

Any file type can be opened in Web Publisher.
Expand Down
11 changes: 10 additions & 1 deletion docs/codeflow/working-in-codeflow-ide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,6 @@ Follow these steps:

To integrate the bot, please follow the instructions on [Integrating CodeflowApp bot](./integrating-codeflowapp-bot.md).


## Troubleshooting

### Out of memory error
Expand All @@ -92,6 +91,10 @@ It may happen that having a few Codeflow IDE or StackBlitz projects open at the

<!-- @include: ../parts/error-out-of-memory.md -->

### Can't switch to a remote branch

Currently, when you load your repository, Codeflow only pulls in the branch you are trying to open or the default one. For now, to switch to a remote branch you can either fetch the branches (by running `git fetch` in the terminal) or immediately open the desired branch through its URL by following this pattern: `http://pr.new/github/${owner}/${repo}/tree/${branchName}`

### Preview doesn't work

If the Preview doesn't work, oftentimes browser configuration or browser incompatibility is the culprit. Please see [this page for troubleshooting](/platform/webcontainers/browser-support).
Expand All @@ -109,3 +112,9 @@ Check in the terminal if the dev server is still running. If you want to restart
### Reopening the Preview panel

If you close the Preview by accident, you can reopen it by selecting the icon of a plug entitled "Ports in use" from the left-side navigation bar. Note that you can open the Preview in a separate tab or as a split screen.

## 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).



1 change: 1 addition & 0 deletions docs/data.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ export const webcontainersLinks = [
{ text: 'Browser configuration', link: '/platform/webcontainers/browser-config' },
{ text: 'Project configuration', link: '/platform/webcontainers/project-config' },
{ text: 'Turbo package manager', link: '/platform/webcontainers/turbo-package-manager' },
{ text: 'Monorepo support', link: '/platform/webcontainers/monorepo-support' },
{ text: 'Troubleshooting', link: '/platform/webcontainers/troubleshooting-webcontainers' },
];

Expand Down
70 changes: 70 additions & 0 deletions docs/parts/monorepo-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
You can also see demos for each of the package managers in this [monorepo demo collection](https://stackblitz.com/@d3lm/collections/workspaces).

### npm

Your project repository may look like this:

```
workspace-project
├─ packages
│ ├─ backend
│ │ ├─ package.json
│ │ └─ index.js
│ ├─ frontend
│ │ ├─ package.json
│ │ └─ index.js
│ └─ common
│ ├─ package.json
│ └─ index.js
└─ package.json
```

To define a workspace, add the `workspaces` field to the `package.json`:

```
"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).

```

This refers to every sub-directory inside `packages` which contains a `package.json`.

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


To configure a workspace with pnpm, add the `pnpm-workspace.yaml` file to the root of the project:

```yaml
packages:
- 'packages/*'
```

Next, add a package from the workspace as a dependency to another package. In the example below we define `frontend` as dependent on `common`:

```json
"dependencies": {
"common": "workspace:^1.0.0"
}
```

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



### 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.


To define a workspace with yarn, add the `workspaces` field to our `package.json`:

```
"workspaces": [
"packages/*"
],
```

This refers to every sub-directory inside `packages` which contains a `package.json`.

:::info
Note that a yarn workspace looks somewhat identical to an npm workspace. For the most parts that's true, but yarn also has [`nohoist`](https://classic.yarnpkg.com/blog/2018/02/15/nohoist).
:::
8 changes: 8 additions & 0 deletions docs/platform/webcontainers/monorepo-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: Monorepo support in WebContainers
---

# {{ $frontmatter.title }}


WebContainers support workspaces. Follow a walkthrough below to get your monorepo running in WebContainers. <!-- @include: ../../parts/monorepo-support.md -->
Loading