docs(core): add pnpm + nx course

nrwl · Oct 31, 2024 · 82aade3 · 82aade3
1 parent 2f2dcb5
commit 82aade3
Show file tree

Hide file tree

Showing 22 changed files with 370 additions and 158 deletions.
diff --git a/docs/courses/pnpm-nx-next/course.md b/docs/courses/pnpm-nx-next/course.md
@@ -3,13 +3,16 @@ title: 'From PNPM Workspaces to Distributed CI'
 description: ''
 slug: nx-19-8-update
 authors: [Juri Strumpflohner]
-cover_image: /blog/images/2024-09-20/thumbnail.png
+repository: 'https://github.com/nrwl/nx-course-pnpm-nx'
 ---
 
-**Key takeaways:**
+In this course, we'll walk through a step-by-step guide using the Tasker application as our example. Tasker is a task management app built with Next.js, structured as a PNPM workspace monorepo. The monorepo contains the Next.js application which is modularized into packages that handle data access via Prisma to a local DB, UI components, and more.
 
-- add Nx to an existing PNPM workspace
-- fine tune your repo with local caching, defining task piplines and establishing dependencies among projects
-- connect and configure your workspace with Nx Cloud
-- learn how to debug cache misses and control remote cache access with Nx Cloud
-- automatically split your Playwright e2e tests to optimize CI time from 20 minutes to 9 minutes
+Throughout the course, we'll take incremental steps to enhance the monorepo:
+
+1. Adding Nx
+2. Configuring and fine-tuning local caching
+3. Defining task pipelines to ensure correct task execution order
+4. Optimizing CI configuration with remote caching
+5. Adjusting the current CI configuration to enable task distribution
+6. Splitting and parallelizing Playwright e2e tests to reduce execution time from 20 minutes to 9 minutes
diff --git a/docs/courses/pnpm-nx-next/images/e2e-splitting-anim.gif b/docs/courses/pnpm-nx-next/images/e2e-splitting-anim.gif
diff --git a/docs/courses/pnpm-nx-next/images/implicit-dependencies.avif b/docs/courses/pnpm-nx-next/images/implicit-dependencies.avif
diff --git a/docs/courses/pnpm-nx-next/images/nx-cloud-compare-cache-miss.avif b/docs/courses/pnpm-nx-next/images/nx-cloud-compare-cache-miss.avif
diff --git a/docs/courses/pnpm-nx-next/lessons/00-overview.md b/docs/courses/pnpm-nx-next/lessons/00-overview.md
@@ -1,8 +1,16 @@
 ---
-title: 'Overview'
-videoUrl: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+title: 'Course Intro'
+videoUrl: 'https://youtu.be/VJ1v5dktwwI'
+duration: '1:01'
 ---
 
-# Overview
+In this course, we'll walk through a step-by-step guide using the Tasker application as our example. Tasker is a task management app built with Next.js, structured as a PNPM workspace monorepo. The monorepo contains the Next.js application which is modularized into packages that handle data access via Prisma to a local DB, UI components, and more.
 
-Here's some text related to the overview
+Throughout the course, we'll take incremental steps to enhance the monorepo:
+
+1. Adding Nx
+2. Configuring and fine-tuning local caching
+3. Defining task pipelines to ensure correct task execution order
+4. Optimizing CI configuration with remote caching
+5. Implementing distribution across machines
+6. Optimizing Playwright e2e tests to reduce execution time from 20 minutes to 9 minutes
diff --git a/docs/courses/pnpm-nx-next/lessons/01-nx-init.md b/docs/courses/pnpm-nx-next/lessons/01-nx-init.md
@@ -1,28 +1,18 @@
 ---
-title: 'Initialize the workspace'
-videoUrl: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
-duration: '04:20'
+title: 'Initialize Nx in Your Project with nx init'
+videoUrl: 'https://youtu.be/3hW53b1IJ84'
+duration: '3:42'
 ---
 
-In this lesson we're going to look into how to initialize a new Nx workspace.
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+In this lesson, we'll explore how to add Nx to our existing PNPM workspace. You can either add just the `nx` package to your `package.json` and then create a `nx.json` [configuration file](/reference/nx-json), or simply run:
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+```shell
+nx init
+```
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+This process will analyze your repository and ask you a couple of questions to properly set up Nx while maintaining your existing PNPM workspace structure.
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+## Relevant Links
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+- [Adopting Nx](/recipes/adopting-nx)
+- [Import an Existing Project into an Nx Workspace](/recipes/adopting-nx/import-project)
diff --git a/docs/courses/pnpm-nx-next/lessons/02-configure-caching.md b/docs/courses/pnpm-nx-next/lessons/02-configure-caching.md
diff --git a/docs/courses/pnpm-nx-next/lessons/02-run-tasks.md b/docs/courses/pnpm-nx-next/lessons/02-run-tasks.md
@@ -0,0 +1,23 @@
+---
+title: 'Run and Manage Tasks Efficiently Using Nx'
+videoUrl: 'https://youtu.be/CJLRkzRrcjg'
+duration: '1:56'
+---
+
+In this lesson, you'll learn how to use Nx to run your PNPM workspace's `package.json` scripts. So rather than running:
+
+```shell
+pnpm --filter @tasker/web build
+```
+
+you would run:
+
+```shell
+pnpm nx build @tasker/web
+```
+
+We'll cover the syntax for running both single tasks and multiple tasks, helping you understand how to leverage Nx's task execution capabilities.
+
+## Relevant Links
+
+- [Run Tasks with Nx](/features/run-tasks)
diff --git a/docs/courses/pnpm-nx-next/lessons/03-configure-cache.md b/docs/courses/pnpm-nx-next/lessons/03-configure-cache.md
@@ -0,0 +1,13 @@
+---
+title: 'Configure Cache Outputs to Handle the .next Folder'
+videoUrl: 'https://youtu.be/t8lOa__TD7o'
+duration: '2:07'
+---
+
+By default Nx captures common folders like `dist` or `build` and automatically restores them from the local cache. However, it doesn't capture the `.next` folder by default.
+
+In this lesson, you'll learn how to fine-tune local caching to ensure proper handling of the `.next` folder. We'll configure the cache outputs to make sure the Next.js build artifacts are properly restored from cache when needed.
+
+## Relevant Links
+
+- [Cache Task Results](/features/cache-task-results)
diff --git a/docs/courses/pnpm-nx-next/lessons/04-task-pipelines.md b/docs/courses/pnpm-nx-next/lessons/04-task-pipelines.md
@@ -0,0 +1,28 @@
+---
+title: 'Automate Task Pipelines to Build Before next start'
+videoUrl: 'https://youtu.be/_U4hu6SuBaY'
+duration: '3:07'
+---
+
+All Next.js projects usually come with these `package.json` scripts:
+
+```json {% fileName="package.json" %}
+{
+    ...
+    "scripts": {
+        ...
+        "build": "next build",
+        "start": "next start"
+    }
+}
+```
+
+Running `next start` will only work if the `.next` folder is present in the project's root. This folder is created when running `next build`.
+
+This is a very simple use case of a [task pipeline](/concepts/task-pipeline-configuration), which defines dependencies among tasks.
+
+In this lesson we're going to create a simple task pipeline such that whenever you run `next start`, Nx will automatically run `next build` (or restore it from the cache).
+
+## Relevant Links
+
+- [Defining a Task Pipeline](/recipes/running-tasks/defining-task-pipeline)
diff --git a/docs/courses/pnpm-nx-next/lessons/05-implicit-dependencies.md b/docs/courses/pnpm-nx-next/lessons/05-implicit-dependencies.md
@@ -0,0 +1,27 @@
+---
+title: 'Link an e2e Project with Its Web App Through Implicit Dependencies'
+videoUrl: 'https://youtu.be/-iUHY27qUfE'
+duration: '2:38'
+---
+
+One of the main capabilities of Nx is that it builds a project graph behind the scenes which it uses optimize how it runs your tasks. You can visualize the graph using:
+
+```shell
+pnpm nx graph
+```
+
+{% callout type="info" title="Install Nx Console" %}
+
+You can also install **Nx Console** which is an extension for VSCode and IntelliJ that enhances the DX when working with Nx monorepos among which there's also the ability to visualize the project graph right in your editor window. Read more [about it here](/getting-started/editor-setup).
+
+{% /callout %}
+
+While most of the relationships are discovered by Nx automatically via `package.json` dependencies or JS/TypeScript imports, some cannot be detected. E2E projects such as the Playwright project in our workspace doesn't directly depend on our Next.js application. There is a dependency at runtime though, because Playwright needs to serve our Next application in order to be ablet to run its e2e tests.
+
+![Implicit dependencies](/courses/pnpm-nx-next/images/implicit-dependencies.avif)
+
+In this lesson, you'll learn how to define such dependencies using the `implicitDependencies` property.
+
+## Relevant Links
+
+- [Project configuration: implicitDependencies](/reference/project-configuration#implicitdependencies)
diff --git a/docs/courses/pnpm-nx-next/lessons/06-nx-cloud-setup.md b/docs/courses/pnpm-nx-next/lessons/06-nx-cloud-setup.md
@@ -0,0 +1,13 @@
+---
+title: 'Connect Your Workspace to Nx Cloud'
+videoUrl: 'https://youtu.be/8mqHXYIl_qI'
+duration: '4:00'
+---
+
+Nx powers the “Smart Monorepo,” while Nx Cloud brings “Fast CI” into the mix. Designed to extend Nx’s efficiency into the CI pipeline, Nx Cloud ensures that even large monorepos stay fast and optimized in CI.
+
+In this lesson, we’ll take the Tasker monorepo, push it to GitHub, set up an Nx Cloud workspace, and link it with your GitHub repository. By the end, your Nx workspace will be fully connected to Nx Cloud, ready to leverage its remote caching and distributed CI capabilities.
+
+## Relevant Links
+
+- [Connect to Nx Cloud](/ci/intro/connect-to-nx-cloud)
diff --git a/docs/courses/pnpm-nx-next/lessons/07-optimize-ci.md b/docs/courses/pnpm-nx-next/lessons/07-optimize-ci.md
@@ -0,0 +1,20 @@
+---
+title: 'Use Nx Commands on CI'
+videoUrl: 'https://youtu.be/ywlilx9-jNk'
+duration: '4:43'
+---
+
+The Tasker project already uses a CI script on GitHub Actions, but in this lesson, we’ll enhance it by replacing the existing `pnpm --filter` commands with optimized Nx commands for a more efficient CI pipeline.
+
+We’ll cover how to scaffold a new CI configuration with:
+
+```shell
+pnpm nx g ci-workflow
+```
+
+We’ll also take a quick detour to discuss `namedInputs` in `nx.json`, ensuring the cache invalidates appropriately whenever the CI config is updated.
+
+## Relevant Links
+
+- [Run Only Tasks Affected by a PR](/ci/features/affected)
+- [Tutorial: Github Actions with Nx](https://nx.dev/ci/intro/tutorials/github-actions#create-a-ci-workflow)
diff --git a/docs/courses/pnpm-nx-next/lessons/08-remote-caching.md b/docs/courses/pnpm-nx-next/lessons/08-remote-caching.md
@@ -0,0 +1,13 @@
+---
+title: 'Configure CI to Access Remote Caching'
+videoUrl: 'https://youtu.be/vBokLJ_F8qs'
+duration: '1:45'
+---
+
+Nx Cloud comes with powerful built-in [remote caching capabilities](/ci/features/remote-cache). Security and access control for such a cache is crucial, which is why Nx Cloud provides [various controls for managing read and write access to the remote cache](/ci/features/access-control).
+
+In this lesson, we'll create an access token in our Nx Cloud workspace configuration to enable read/write access to our Github actions.
+
+## Relevant Links
+
+- [Nx CLI and CI Access Tokens](/ci/recipes/security/access-tokens)
diff --git a/docs/courses/pnpm-nx-next/lessons/09-debug-cache.md b/docs/courses/pnpm-nx-next/lessons/09-debug-cache.md
@@ -0,0 +1,15 @@
+---
+title: 'Debug Remote Cache misses with Nx Cloud'
+videoUrl: 'https://youtu.be/zJmhW1iIxpc'
+duration: '0:53'
+---
+
+Understanding what causes remote cache misses versus cache hits is crucial for optimization.
+
+![Nx Cloud UI to compare cache misses](/courses/pnpm-nx-next/images/nx-cloud-compare-cache-miss.avif)
+
+In this lesson, we'll explore how Nx Cloud enables you to compare runs and identify what changes led to cache misses.
+
+## Relevant Links
+
+- [Troubleshoot cache misses](/troubleshooting/troubleshoot-cache-misses)
diff --git a/docs/courses/pnpm-nx-next/lessons/10-nx-login.md b/docs/courses/pnpm-nx-next/lessons/10-nx-login.md
@@ -0,0 +1,23 @@
+---
+title: 'Enable Remote Caching for your Developer Machine with Nx Login'
+videoUrl: 'https://youtu.be/vX-wgI1zlao'
+duration: '1:38'
+---
+
+Do you want to allow your developers working on the Tasker monorepo
+
+- to benefit from remote cache results (read-only access)
+- to also contribute to the remote cache (read/write access)
+
+It really depends on your use case. Nx Cloud uses Personal Access Tokens (PAT) to give you a fine-grained control mechanism how local workspaces should access the remote cache.
+
+In this lesson, we'll dive into how to configure your Personal Access Token permissions on Nx Cloud and how developers can authenticate with the Nx Cloud workspace using:
+
+```shell
+pnpm nx login
+```
+
+## Relevant Links
+
+- [Nx Cloud and Personal Access Tokens](/ci/recipes/security/personal-access-tokens)
+- [Blog: Better security with Personal Access Tokens](/blog/personal-access-tokens)
diff --git a/docs/courses/pnpm-nx-next/lessons/11-nx-agents.md b/docs/courses/pnpm-nx-next/lessons/11-nx-agents.md
@@ -0,0 +1,19 @@
+---
+title: 'Run Tasks in Parallel on Different Machines on CI'
+videoUrl: 'https://youtu.be/lO_p4tA6IZI'
+duration: '2:08'
+---
+
+While remote caching is powerful, it may not be enough when core packages change frequently, invalidating the cache for large portions of your workspace.
+
+Nx Cloud comes with a built-in feature called [Nx Agents](/ci/features/distribute-task-execution) that allows to automatically distribute tasks across multiple machines.
+
+In this lesson we're going to update the existing CI configuration to enable Nx Agents. Which mostly can be done by adding the following line:
+
+```plaintext
+nx-cloud start-ci-run --distribute-on="5 linux-medium-js"
+```
+
+## Relevant Links
+
+- [Distribute Task Execution](/ci/features/distribute-task-execution)
diff --git a/docs/courses/pnpm-nx-next/lessons/12-playwright-split.md b/docs/courses/pnpm-nx-next/lessons/12-playwright-split.md
@@ -0,0 +1,15 @@
+---
+title: 'Split Playwright e2e Tests for a Faster CI'
+videoUrl: 'https://youtu.be/42XnmzxEXM8'
+duration: '5:47'
+---
+
+Running e2e tests on CI can be quite a painful experience. You want them to run on each PR to get immediate feedback, but then you don't want to wait for 30 minutes.
+
+In this lesson, we'll optimize the existing Playwright end-to-end tests that currently take up to 20 minutes on CI. We'll leverage the Nx Playwright plugin to automatically split the Playwright tests into individual runs per test, allowing for optimal distribution across Nx agents and significantly improving CI execution time.
+
+![](/courses/pnpm-nx-next/images/e2e-splitting-anim.gif)
+
+## Relevant Links
+
+- [Automatically Split E2E Tasks](/ci/features/split-e2e-tasks)
diff --git a/docs/courses/pnpm-nx-next/lessons/13-outro.md b/docs/courses/pnpm-nx-next/lessons/13-outro.md
@@ -0,0 +1,7 @@
+---
+title: 'Course Outro'
+videoUrl: 'https://youtu.be/a_pfLrvf88E'
+duration: '0:39'
+---
+
+Thank you for completing this course on optimizing your PNPM workspace with Nx. You've learned how to implement and configure Nx, set up efficient caching, optimize CI processes, and improve e2e test execution times.
diff --git a/docs/shared/getting-started/intro.md b/docs/shared/getting-started/intro.md
@@ -51,7 +51,7 @@ Also, here are some recipes that give you more details based on the technology s
 
 {% link-card title="What is Nx Cloud?" type="video" url="https://youtu.be/4VI-q943J3o" icon="nxcloud" /%}
 
-{% link-card title="PNPM Monorepos with Nx" type="video" url="https://youtu.be/ngdoUQBvAjo" icon="pnpm" /%}
+{% link-card title="PNPM Workspaces to Distributed CI" type="course" url="/courses/pnpm-nx-next" icon="pnpm" /%}
 
 {% link-card title="More On Youtube" type="video" url="https://www.youtube.com/@nxdevtools" icon="youtube" /%}
 

diff --git a/nx-dev/ui-common/src/lib/default-layout.tsx b/nx-dev/ui-common/src/lib/default-layout.tsx
@@ -33,7 +33,7 @@ export function DefaultLayout({
           {children}
         </main>
       </div>
-      {!hideFooter && <Footer />}
+      <Footer className={hideFooter ? 'hidden' : ''} />
     </div>
   );
 }