Itay/update getting started

docs/apps/___create-app.md

@@ -0,0 +1,6 @@
+---
+id: create-app
+title: Create an App
+---
+
+...

docs/apps/___overview.md

@@ -0,0 +1,10 @@
+---
+id: overview
+title: Overview
+---
+
+...
+
+## What is an app component?
+
+..

docs/apps/___recomposing-apps.md

@@ -0,0 +1,6 @@
+---
+id: recomposing-apps
+title: Recomposing Apps
+---
+
+..

docs/apps/deploy-app/___aws.md

@@ -0,0 +1,6 @@
+---
+id: aws
+title: AWS
+---
+
+...

docs/apps/deploy-app/___netlify.md

@@ -0,0 +1,6 @@
+---
+id: netlify
+title: Netlify
+---
+
+..

docs/apps/deploy-app/___vercel.md

@@ -0,0 +1,6 @@
+---
+id: vercel
+title: Vercel
+---
+
+...

docs/aspects/builder/builder.mdx

@@ -1,6 +1,6 @@
 ---
 id: builder
-title: Builder
+title: Build Pipelines
 slug: /aspects/builder
 description: build components on isolated directories
 ---

docs/aspects/dependency-resolver/dependency-resolver.mdx

@@ -7,7 +7,6 @@ description: Simplifies the dependency management of components in a Bit workspa
 
 Check out the [Dependency Resolver Aspect](https://bit.dev/teambit/dependencies/dependency-resolver) on Bit.dev
 
-
 The [Dependency Resolver](https://bit.dev/teambit/dependencies/dependency-resolver) configures and installs dependencies for components in a Bit workspace. It auto-generates the dependency graph for components to spare us the tedious work of manually configuring it ourselves.
 It does so by integrating the dependency policies set by various Bit extensions (primarily the workspace) with the components' parsed and analyzed `import`/`require` statements.
 In addition to that, the Dependency Resolver offers an efficient API to manually modify the generated graph using policies that can be applied on groups of components.
@@ -256,9 +255,9 @@ Set the `devFilePatterns` property to add your own list of file extensions to be
 
 #### peer dependencies
 
-Setting a package as a peer dependency ensures the package manager installs only a single version of that package. If that is not possible, i.e. if there is no single “agreed upon” version for all components in the workspace, then an error will be thrown.
+Setting a package as a peer dependency ensures the package manager installs only a single version of that package. If that is not possible, i.e. if there is no single "agreed upon" version for all components in the workspace, then an error will be thrown.
 
-This can be crucial when different components communicate with each other using shared objects that are instantiated by an installed package (the dependency). If different versions of the same package create different object instances then the “means of communication” is broken. There is no single object to address, no single source of truth. This can turn out to be critical when working with modules that are used as “plugins” of another module (for example, Babel), or when working with components that are coordinated in runtime using a shared library (for example, React).
+This can be crucial when different components communicate with each other using shared objects that are instantiated by an installed package (the dependency). If different versions of the same package create different object instances then the "means of communication" is broken. There is no single object to address, no single source of truth. This can turn out to be critical when working with modules that are used as "plugins" of another module (for example, Babel), or when working with components that are coordinated in runtime using a shared library (for example, React).
 
 To set a package as a peer dependency, place it under the `peerDependencies` entry, like so:
 
@@ -349,8 +348,8 @@ Read about setting a proxy in NPM's global configuration [here](https://docs.npm
 > If that token cannot be found in the `.npmrc` file, Bit will look for it in your global Bit configurations (use the `bit config` command to output your `user.token` property).
 >
 > <br />
-> If your npm is configured to use a registry other than npmjs's, then the Dependency Resolver will use that configured registry,
-> instead.
+> If your npm is configured to use a registry other than npmjs's, then the Dependency
+> Resolver will use that configured registry, instead.
 
 > The 'install' process includes importing components and linking them to the `node_modules` directory.
 

docs/aspects/mdx/index.ts

@@ -1 +1,2 @@
 export { default as Mdx } from './mdx.mdx';
+

docs/builder/___build-on-ci.md

@@ -0,0 +1,6 @@
+---
+id: build-on-ci
+title: Build on CI
+---
+
+...

docs/builder/___component-build.md

@@ -0,0 +1,6 @@
+---
+id: component-build
+title: Component Build
+---
+
+...

docs/builder/build-pipeline-customization.mdx

@@ -0,0 +1,279 @@
+---
+id: build-pipeline-customization
+title: Build Pipeline Customization
+---
+
+The `BuildTask` interface is a good start to understand how to implement a new build-task.
+When writing a build task, the `Network` object is passed and it includes the seeders capsules, as well as the entire graph including the dependencies.
+Keep in mind that the entire graph may contain components from other envs.
+
+Some tasks, such as, compiling in typescript and bundling with Webpack, need the entire graph.
+Others, such as, Babel, need only the seeders. However, normally, the bundling is running after the compilation and it expects to have the dependencies compiled, so you might need the entire graph regardless.
+
+## Adding Tasks to a pipeline
+
+There are two ways of adding tasks to the build pipeline.
+
+1. `getBuildPipe()` method of the env. (or `getTagPipe()` and `getSnapPipe()`)
+2. registering to the slot via `builder.registerBuildTask()`. (or `registerTagTask()` and `registerSnapTask()`)
+
+in the option #1, it's possible to determine the order. e.g. `getBuildPipe() { return [taskA, taskB, taskC]; }`
+in the option #2, the register happens once the extension is loaded, so there is no way to put
+one task before/after another task as of now.
+
+## Sequencing the build tasks
+
+The Build Pipeline takes into consideration the following factors when deciding the order of which to execute each task:
+
+- **Location**: A task can be executed either at the start or end of the build pipeline. This can be explicitly configured by the task itself.
+- **Dependencies**: A task can depend on other tasks. That means, the dependencies must be completed successfully for all envs before this task starts. The dependencies are applicable inside a location and not across locations. This is configured by the task itself.
+- **An environment's list of build tasks**: This is the array of tasks as it is defined by an environment
+
+## Executing the pipelines
+
+Commands that trigger the build pipeline:
+
+- `bit build` - runs the build pipeline on your local machine, for the entire workspace. The output data will not persist. - That is most often used for testing and debugging the build process.
+- `bit tag` - runs the tag pipeline in addition to the build pipeline, before creating a new component release version. The output data will persist.
+- `bit snap` - runs the snap pipeline in addition to the build pipeline. The output data will persist.
+
+Build pipelines are determined by the environments in use. That means, in order to override the default pipeline, we need to create a new environment extension or modify an existing one.
+
+The example task below, shown being used by a customized environment, prints out the component name of every component handled by it. In addition to that, the task returns the component name as custom metadata to be logged and/or stored in the component tagged version. [See a demo project here](https://github.com/teambit/harmony-build-examples).
+
+> Information returned by a build task will only persist if the build-pipeline was triggered by the 'hard-tag' command (`bit tag <component-id>`).
+
+```ts title="print-cmp-name-task.ts"
+import { BuildTask, BuildContext, BuiltTaskResult, ComponentResult } from '@teambit/builder';
+
+// A task is an implementation of 'BuildTask' provided by the 'builder' aspect
+export class PrintCmpNameTask implements BuildTask {
+  // The constructor leaves these properties up to the hands of the environment using this task
+  constructor(readonly aspectId: string, readonly name: string) {}
+
+  // This is where the task logic is placed. It will be executed by the build pipeline
+  async execute(context: BuildContext): Promise<BuiltTaskResult> {
+    const componentsResults: ComponentResult[] = [];
+
+    // Go through every isolated component instance
+    context.capsuleNetwork.seedersCapsules.forEach((capsule) => {
+      console.log(`The current component name is: ${capsule.component.id.name}`);
+
+      componentsResults.push({
+        component: capsule.component,
+        metadata: { customProp: capsule.component.id.name },
+      });
+    });
+    return {
+      // An array of component objects, enriched with additional data produced by the task
+      componentsResults,
+    };
+  }
+}
+```
+
+```ts title="customized-react.extension.ts"
+import { EnvsMain, EnvsAspect } from '@teambit/envs';
+import { ReactAspect, ReactMain } from '@teambit/react';
+
+// Import the task
+import { PrintCmpNameTask } from './print-cmp-name-task';
+
+export class CustomReact {
+  constructor(private react: ReactMain) {}
+
+  static dependencies: any = [EnvsAspect, ReactAspect];
+
+  static async provider([envs, react]: [EnvsMain, ReactMain]) {
+    // Get the environment's default build pipeline
+    const reactPipe = react.env.getBuildPipe();
+
+    // Add the custom task to the end of the build tasks sequence.
+    // Provide the task with the component ID of the extension using it.
+    // Provide the ask with a name.
+    const tasks = [...reactPipe, new PrintCompTask('extensions/custom-react', 'PrintCmpNameTask')];
+
+    // Create a new environment by merging these configurations with the env's default ones
+    const customReactEnv = react.compose([react.overrideBuildPipe(tasks)]);
+
+    // register the extension as an environment
+    envs.registerEnv(customReactEnv);
+    return new CustomReact(react);
+  }
+}
+```
+
+## Positioning a build task in the pipeline
+
+A build task is positioned in the build pipeline sequence either by overriding the entire _customizable_ pipeline or, by registering it to a location in the pipeline using the designated builder slot.
+
+### Override the build pipeline sequence
+
+This methodology leaves the task completely agnostic as to its position in the build pipeline. Instead, the task position is determined by the environment using the `getBuildPipe` Environment Handler.
+
+The example above shows the React environment `overrideBuildPipe` method being used to override its default pipeline. This method uses the `getBuildPipe()` Environment Handler, internally.
+
+### Append to the start or end of the pipeline, in relation to other tasks
+
+This methodology places the task at the start or end of the build pipeline sequence, and lists all other tasks needed to run successfully before it is executed.
+
+Example:
+
+```ts title="print-cmp-name-task.ts"
+import { BuildTask, BuildContext, BuiltTaskResult, ComponentResult } from '@teambit/builder';
+
+export class PrintCmpNameTask implements BuildTask {
+  constructor(readonly aspectId: string, readonly name: string) {}
+
+  // Place the task at the end of the build pipeline
+  readonly location = 'end';
+
+  // Run this task only after the '@teambit/preview' task is completed successfully
+  readonly dependencies = ['@teambit/preview'];
+
+  async execute(context: BuildContext): Promise<BuiltTaskResult> {
+    const componentsResults: ComponentResult[] = [];
+    context.capsuleNetwork.seedersCapsules.forEach((capsule) => {
+      console.log(`The current component name is: ${capsule.component.id.name}`);
+
+      componentsResults.push({
+        component: capsule.component,
+        metadata: { customProp: capsule.component.id.name },
+      });
+    });
+    return {
+      componentsResults,
+    };
+  }
+}
+```
+
+```ts title="customized-react.extension.ts"
+import { EnvsMain, EnvsAspect } from '@teambit/envs';
+import { ReactAspect, ReactMain } from '@teambit/react';
+import { BuilderMain } from '@teambit/builder';
+
+// Import the task (in reality, it should be an independent component)
+import { PrintCmpNameTask } from './print-cmp-name-task';
+
+export class CustomReact {
+  constructor(private react: ReactMain) {}
+
+  static dependencies: any = [EnvsAspect, ReactAspect];
+
+  // Inject the builder
+  static async provider([envs, react, builder]: [EnvsMain, ReactMain, BuilderMain]) {
+    // Register this task using the registration slot, made available by the 'builder'.
+    // Here, the environment has no say in the positioning of the task
+    builder.registerBuildTasks([new ExampleTask('extensions/custom-react', 'PrintCmpNameTask')]);
+
+    const customReactEnv = react.compose([]);
+
+    envs.registerEnv(customReactEnv);
+    return new CustomReact(react);
+  }
+}
+```
+
+## A build task anatomy
+
+- **aspectId** <br />
+  `aspectId: string`<br />
+  The component ID of the environment using this task.
+
+- **name** <br />
+  `name: string` <br />
+  A name for this task. Only alphanumerical characters are allowed. PascalCase should be used as a convention.
+
+- **location** <br />
+  `location?: 'start' | 'end'` <br />
+  The section of the build-pipeline to which to append this task.
+
+- **dependencies** <br />
+  `dependencies?: string[]` <br />
+  An list of tasks that must be completed before this task gets executed. <br />
+  For example `dependencies = ['@teambit/preview']`.
+
+- **execute** <br />
+  `execute(context: BuildContext): Promise<BuiltTaskResult>` <br />
+  The execute method is where all the task logic is placed.
+
+  - **context** (argument) <br />
+    `context: BuildContext` <br />
+    The context of the build pipeline. Use this object (provided by the build pipeline) to get information regarding all components handled by the build pipeline. <br /><br />
+    For example, `context.capsuleNetwork.seedersCapsules` are models representing isolated instances of components handled by the build pipeline. These isolated instances are independent projects, generated in your local filesystem (by the build pipeline).
+
+  - **return** <br />
+    `Promise<BuiltTaskResult>` <br />
+    A `context` method returns an object with data regarding the build task process, additional data regarding the components handled by the task and, if available, data regarding the different artifacts generated by this task.<br />
+    The returned object has the following attributes:
+
+    - **componentsResults** <br />
+      `componentsResults: ComponentResult[]`
+      An array of objects, each containing an instance of an object handled the task and additional information regarding the process and the component itself.
+    - **component** <br />
+      `component: Component` <br />
+      An instance of the component handled by the task (see the above task example).
+
+    - **metadata** <br />
+      `metadata?: { [key: string]: Serializable }` <br />
+      Component metadata generated during the build task.
+
+    - **errors** <br />
+      `errors?: Array<Error | string>` <br />
+      Build task errors. A task returning errors will abort the build pipeline and log the returned errors.
+
+    - **warnings** <br />
+      `warnings?: string[]` <br />
+      warnings generated throughout the build task.
+
+    - **startTime** <br />
+      `startTime?: number` <br />
+      A timestamp (in milliseconds) of when the task started
+
+    - **endTime** <br />
+      `endTime?: number` <br />
+      A timestamp (in milliseconds) of when the task ended
+    - **artifacts** <br />
+      `artifacts?: ArtifactDefinition[]` <br />
+      An array of artifact definitions to generate after a successful build
+    - **name** <br />
+      `name: string` <br />
+      The name of the artifact. <br />
+      For example, a project might utilize two different artifacts for the same typescript compiler, one that generates ES5 files and another for ES6. This prop helps to distinguish between the two.
+    - **generatedBy** <br />
+      `generatedBy?: string;` <br />
+      Id of the component that generated this artifact.
+
+    - **description** <br />
+      `description?: string` <br />
+      A description of the artifact. <br />
+
+    - **globPatterns** <br />
+      `globPatterns: string[]` <br />
+      Glob patterns of files to include upon artifact creation. Minimatch is used to match the patterns. <br />
+      For example, `['*.ts', '!foo.ts']` matches all ts files but ignores `foo.ts`.
+
+    - **rootDir** <br />
+      `rootDir?: string` <br />
+      Defines the root directory of the artifacts in the capsule file system. The rootDir must be unique for every artifact, otherwise data might be overridden.
+
+    - **dirPrefix** <br />
+      `dirPrefix?: string` <br />
+      Adds a directory prefix for all artifact files.
+
+    - **context** <br />
+      `context?: 'component' | 'env'` <br />
+      Determine the context of the artifact. The default artifact context is `component`. `env` is useful when the same file is generated for all components, for example, a "preview" task may create the same webpack file for all components of that env.
+
+    - **storageResolver** <br />
+      `storageResolver?: string` <br />
+      Used to replace the location of the stored artifacts. The default resolver persists artifacts on scope (that's not recommended for large files).
+
+- **preBuild** (advanced) <br />
+  `preBuild?(context: BuildContext): Promise<void>` <br />
+  Runs before the build pipeline has started. This method should only be used when preparations are needed to be done on all environments before the build starts.
+
+- **postBuild** (advanced) <br />
+  `postBuild?(context: BuildContext, tasksResults: TaskResultsList): Promise<void>` <br />
+  Runs after the dependencies were completed for all environments.