Revert "Temporarily remove docs folder." (#8334)

Reverts #8329

See https://vercel.slack.com/archives/C02F56A54LU/p1717614092236519

docs/pages/messages/_meta.json

@@ -0,0 +1,6 @@
+{
+  "invalid-env-prefix": "Invalid Environment Variable Prefix",
+  "package-task-in-single-package-mode": "Package Task In Single Package Mode",
+  "turbo-json-parse-error": "`turbo.json` Parse Error",
+  "unnecessary-package-task-syntax": "Unnecessary Package Task Syntax"
+}

docs/pages/messages/invalid-env-prefix.mdx

@@ -0,0 +1,32 @@
+---
+title: Invalid environment variable prefix
+description: Invalid environment variable prefix error
+---
+
+# Invalid environment variable prefix
+
+## Why This Error Occurred
+
+When declaring environment variables in your `turbo.json`, you cannot prefix them with `$`. This
+was an old syntax for declaring a dependency on an environment variable that was deprecated in Turbo 1.5.
+
+```json
+{
+  "globalEnv": ["$MY_ENV_VAR"]
+}
+```
+
+The environment variable declared above has the `$` prefix.
+
+## Solution
+
+Remove the `$` prefix from your environment variable declaration.
+
+```json
+{
+  "globalEnv": ["MY_ENV_VAR"]
+}
+```
+
+You can migrate to the env and globalEnv keys using `npx @turbo/codemod migrate-env-var-dependencies`.
+Check out [the codemod's documentation for more details](/repo/docs/reference/codemods#migrate-env-var-dependencies).

docs/pages/messages/missing-root-task-in-turbo-json.mdx

@@ -0,0 +1,52 @@
+---
+title: Missing root task in turbo.json
+description: Missing root task in turbo.json error
+---
+
+# Missing root task in turbo.json
+
+## Why This Error Occurred
+
+Root tasks are the scripts defined in the monorepo's root `package.json`. These tasks often call `turbo`. For example:
+
+```json package.json
+{
+  "scripts": {
+    "build": "turbo run build"
+  }
+}
+```
+
+This creates a problem when we declare [topological dependencies](/repo/docs/reference/configuration#dependson). Topological
+dependencies specify that your package's dependencies should execute their tasks before your package executes its own task.
+
+```json turbo.json
+{
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+Because the root package is a dependency for all packages inside your workspace, its task would get executed first.
+But since its task calls `turbo`, this would cause an infinite loop.
+
+## Solution
+
+As long as the root task does _not_ call `turbo`, you can add it to the `pipeline` field in `turbo.json`:
+
+```json
+{
+  "pipeline": {
+    "//#build": {}
+  }
+}
+```
+
+This will permit tasks to depend on `//#build`.
+
+However, if the root task does call `turbo`, this can cause infinite recursion. In this case, we don't recommend depending
+on the root task. Instead, you can determine the tasks that this root task depends on, and depend on those directly.
+For instance, if `//#build` depends on `app#lint` and `docs#lint`, then you can declare those as dependencies.

docs/pages/messages/package-task-in-single-package-mode.mdx

@@ -0,0 +1,37 @@
+---
+title: Package task in single package mode
+description: Package task in single package mode error
+---
+
+# Package task in single package mode
+
+## Why This Error Occurred
+
+In single package mode, there cannot be multiple packages in your repository. Therefore, declaring a task in the
+`turbo.json` with a specified package name is not permitted.
+
+```json
+{
+  "pipeline": {
+    "app#build": {
+      "cache": true
+    }
+  }
+}
+```
+
+## Solution
+
+Remove the package name from the task declaration.
+
+```json
+{
+  "pipeline": {
+    "build": {
+      "cache": true
+    }
+  }
+}
+```
+
+Alternatively, if you would like to have multiple packages, you can [specify the workspaces in your repository](/repo/docs/getting-started/existing-monorepo#configure-workspaces).

docs/pages/messages/unnecessary-package-task-syntax.mdx

@@ -0,0 +1,42 @@
+---
+title: Unnecessary package task syntax
+description: Unnecessary package task syntax error
+---
+
+# Unnecessary package task syntax
+
+## Why This Error Occurred
+
+Turborepo supports adding additional `turbo.json` files in a package directory
+to override the `turbo.json` file declared at the repository root, a feature called [Workspace Configurations](/repo/docs/core-concepts/monorepos/configuring-workspaces).
+In those additional `turbo.json` files, you can only configure tasks for that specific
+package. Therefore, only the task name should be included in the pipeline,
+not the package and task name (`package#task`).
+
+`turbo.json` file in `apps/web` directory:
+
+```json
+{
+  "pipeline": {
+    "web#build": {
+      "dependsOn": ["lint"]
+    }
+  }
+}
+```
+
+Since this `turbo.json` file is inside a package directory, the `web` prefix is unnecessary.
+
+## Solution
+
+Remove the package prefix from the task name:
+
+```json
+{
+  "pipeline": {
+    "build": {
+      "dependsOn": ["lint"]
+    }
+  }
+}
+```

docs/pages/pack/_meta.json

@@ -0,0 +1,15 @@
+{
+  "index": {
+    "type": "page",
+    "display": "hidden",
+    "theme": {
+      "layout": "raw",
+      "sidebar": false,
+      "toc": true
+    }
+  },
+  "docs": {
+    "title": "Docs",
+    "display": "children"
+  }
+}

docs/pages/pack/docs/_meta.json

@@ -0,0 +1,10 @@
+{
+  "index": "Quickstart",
+  "why-turbopack": "Why Turbopack?",
+  "core-concepts": "Core Concepts",
+  "roadmap": "Roadmap",
+  "features": "Features",
+  "benchmarks": "Benchmarks",
+  "migrating-from-webpack": "Migrating from Webpack",
+  "advanced": "Advanced"
+}

docs/pages/pack/docs/advanced/profiling.mdx

@@ -0,0 +1,74 @@
+---
+title: Profiling
+description: Learn how to profile Turbopack
+---
+
+import { ThemedImageFigure } from '../../../../components/image/ThemedImageFigure';
+
+# Profiling Turbopack
+
+## On macOS
+
+### Install [`cargo-instruments`]
+
+```sh
+cargo install cargo-instruments
+```
+
+Make sure you have all the [prerequisites](https://github.com/cmyr/cargo-instruments#pre-requisites) for running cargo-instruments.
+
+### Run the profiler
+
+By default, `turbopack-cli dev` will keep watching for changes to your application and never exit until you manually interrupt it. However, [`cargo-instruments`] waits for your program to exit before building and opening the trace file. For this purpose, we've added a `profile` feature to `turbopack-cli` which exits the program if no updates are detected within a given time frame and there are no pending tasks.
+
+To profile `turbopack-cli`, run the following command:
+
+```sh
+cargo instruments -t time --bin turbopack-cli --release --features profile [-- [...args]]
+```
+
+You can also run [other templates](https://github.com/cmyr/cargo-instruments#templates) than the time profiler.
+
+Once the program exits, the profiler will open the trace file in Instruments. Refer to the [learning resources](https://github.com/cmyr/cargo-instruments#resources) to learn how to use Instruments.
+
+<ThemedImageFigure
+  borderRadius={true}
+  dark={{
+    source: '/images/docs/pack/instruments-dark.png',
+    height: 662,
+    width: 968
+  }}
+  light={{
+    source: '/images/docs/pack/instruments-light.png',
+    height: 706,
+    width: 1012
+  }}
+  captionSpacing={24}
+  caption="An example trace from the time profiler."
+/>
+
+## Linux
+
+### Memory usage
+
+```sh
+# Install `heaptrack` and `heaptrack_gui`
+sudo apt install heaptrack heaptrack_gui
+
+# Compile with debug info but without the alternative allocator:
+CARGO_PROFILE_RELEASE_DEBUG=1 cargo build --bin turbopack-cli --release --no-default-features --features native-tls
+
+# Run the binary with heaptrack (it will be much slower than usual)
+heaptrack target/release/turbopack-cli [...]
+
+# Stop it anytime
+
+# Open the GUI and open the heaptrack.turbopack-cli.XXX.gz file
+heaptrack_gui
+```
+
+## On other platforms
+
+We currently don't have a guide for profiling Turbopack on other platforms.
+
+[`cargo-instruments`]: https://github.com/cmyr/cargo-instruments

docs/pages/pack/docs/benchmarks.mdx

@@ -0,0 +1,7 @@
+import { Callout } from '../../../components/Callout';
+
+# Benchmarks
+
+<Callout type="info">
+  Check back soon for benchmark results against real-world Next.js Applications when `next dev --turbo` becomes stable.
+</Callout>

docs/pages/pack/docs/core-concepts.mdx

@@ -0,0 +1,44 @@
+---
+title: Core Concepts
+description: Learn about the innovative architecture that powers Turbopack's speed improvements.
+---
+
+# Core Concepts
+
+Let’s dive deep into the internals of Turbopack to figure out why it’s so fast.
+
+## The Turbo engine
+
+Turbopack is so fast because it’s built on a reusable library for Rust which enables incremental computation known as the Turbo engine. Here’s how it works:
+
+### Function-level caching
+
+In a Turbo engine-powered program, you can mark certain functions as ‘to be remembered’. When these functions are called, the Turbo engine will remember **what they were called with**, and **what they returned**. It’ll then save it in an in-memory cache.
+
+Here’s a simplified example of what this might look like in a bundler:
+
+![](/images/docs/pack/turbo-engine-first-run.png)
+
+We start with calling `readFile` on two files, `api.ts` and `sdk.ts`. We then `bundle` those files, `concat` them together, and end up with the `fullBundle` at the end. The results of all of those function calls get saved in the cache for later.
+
+Let’s imagine that we’re running on a dev server. You save the `sdk.ts` file on your machine. Turbopack receives the file system event, and knows it needs to recompute `readFile("sdk.ts")`:
+
+![](/images/docs/pack/turbo-engine-second-run.png)
+
+Since the result of `sdk.ts` has changed, we need to `bundle` it again, which then needs to be concatenated again.
+
+Crucially, `api.ts` hasn’t changed. We read its result from the cache and pass that to `concat` instead. So we save time by not reading it and re-bundling it again.
+
+Now imagine this in a real bundler, with thousands of files to read and transformations to execute. The mental model is the same. You can save enormous amounts of work by remembering the result of function calls and not re-doing work that’s been done before.
+
+### The cache
+
+The Turbo engine currently stores its cache in memory. This means the cache will last as long as the process running it - which works well for a dev server. When you run `next dev --turbo` in Next.js 13+, you’ll start a cache with the Turbo engine. When you cancel your dev server, the cache gets cleared.
+
+In the future, we’re planning to persist this cache - either to the filesystem, or to a remote cache like Turborepo’s. This will mean that Turbopack could remember work done _across runs and machines._
+
+### How does it help?
+
+This approach makes Turbopack extremely fast at computing incremental updates to your apps. This optimizes Turbopack for handling updates in development, meaning your dev server will always respond snappily to changes.
+
+In the future, a persistent cache will open the door to much faster production builds. By remembering work done _across runs_, new production builds could only rebuild changed files - potentially leading to enormous time savings.

docs/pages/pack/docs/features.mdx

@@ -0,0 +1,22 @@
+---
+title: Features
+description: Learn about Turbopack's supported features
+---
+
+import { TurbopackFeatures } from '../../../components/TurbopackFeatures'
+
+# Features
+
+The practice of building web applications is enormously diverse. In CSS alone, you have SCSS, Less, CSS Modules, PostCSS, and hundreds of other libraries. Frameworks like React, Vue and Svelte require custom setups.
+
+When building a bundler, we needed to consider which features would be:
+
+- **Built-in**: they work out of the box, no config required
+- **Available via plugins**: usually installed from a registry and configured
+- **Unavailable**: not available at all
+
+**Turbopack is in beta**, so very few of these decisions are set in stone. In its current state, **Turbopack cannot yet be configured** - so plugins are not available yet.
+
+Let's discuss which features are available out-of-the-box, in Turbopack's default configuration. We'll also touch on features which will be configurable via plugins.
+
+<TurbopackFeatures />

docs/pages/pack/docs/features/_meta.json

@@ -0,0 +1,9 @@
+{
+  "javascript": "JavaScript",
+  "typescript": "TypeScript",
+  "frameworks": "Frameworks",
+  "css": "CSS",
+  "dev-server": "Dev Server",
+  "static-assets": "Static Assets",
+  "imports": "Imports"
+}