@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/en/guides/basic-features/deploy.mdx

@@ -0,0 +1,448 @@
+---
+sidebar_position: 15
+---
+
+# Deploy Application
+
+Currently, Modern.js offers two deployment way:
+
+- You can host your application in a container that includes a Node.js environment on your own, which provides flexibility for the deployment of the application.
+- You can also deploy your application through a platform. Currently, Modern.js officially supports deployment on [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/), and [Github pages](https://pages.github.com/).
+
+:::info
+Currently, Modern.js only supports running in a Node.js environment. Support for more runtime environments will be provided in the future.
+:::
+
+## Build Deployment Products
+
+Running the `modern deploy` command will automatically produce deployment products. This process includes optimizing Bundler build products and their dependencies, detecting the current deployment platform, and automatically generating deployment products that can run on that platform.
+
+If you want to generate and test the output locally for a specific deployment platform, you can specify the platform by setting the environment variable: `modern deploy`:
+
+```bash
+MODERNJS_DEPLOY=netlify npx modern deploy
+```
+
+:::info
+When deploying on the deployment platforms officially supported by Modern.js, there is no need to specify environment variables.
+:::
+
+## Using ModernJS built-in Node.js Server
+
+### Single Repo
+
+By default, Modern.js outputs builds that can be run in a Node.js environment when no Modern.js-supported deployment platform is detected.
+
+Use the following command to build the project:
+
+```bash
+npx modern deploy
+```
+
+When running the `modern deploy` command, Modern.js will generate runnable products and output the following content in terminal:
+
+```bash
+Static directory: `.output/static`
+You can preview this build by `node .output/index`
+```
+
+At this point, you can run the entire server by `node .output/index`, and the static resources required for the page are in the `.output/static` directory. You can upload these static resources to a CDN yourself:
+
+:::info
+By default, when running Modern.js Server, it listens on port 8080. If you want to change the listening port, you can specify the `PORT` environment variable:
+
+```
+PORT=3000 node .output/index
+```
+
+:::
+
+### Monorepo
+
+For Monorepo projects, in addition to building the current project, it is also necessary to build other sub-projects in the repository that the current project depends on.
+
+Assume that the name in the `package.json` of the current project is `app`. Taking pnpm as an example of a monorepo management tool, you can add the following command to the `package.json` of the current project to build products for the current project:
+
+```json title="app/package.json"
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy"
+  }
+}
+```
+
+If you use Rush as your Monorepo management tool, you can add the following commands to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build:packages": "rush rebuild --to-except app",
+    "deploy": "rushx build:packages && modern deploy"
+  }
+}
+```
+
+After the build is completed, Modern.js will generate all dependencies in the `.output/node_modules` directory of the project. Similarly, you can run the Modern.js server using `node .output/index`.
+
+## Netlify
+
+Netlify is a popular Web development platform designed for building, deploying, and maintaining modern web projects. Deploying on Netlify mainly requires configuring the `netlify.toml` file.
+
+Depending on the complexity of your project, you can configure it incrementally by this doc.
+
+### Pure Front-end Project
+
+Add the `netlify.toml` file to the root directory of the current project:
+
+```bash
+.
+├── src
+├── modern.config.ts
+├── netlify.toml
+└── package.json
+```
+
+Add the following content to `netlify.toml`:
+
+```toml
+[build]
+  publish = "dist"
+  command = "modern deploy"
+```
+
+:::info
+You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+
+:::
+
+Now, add a project to the Netlify platform and deploy it!
+
+### Full Stack Project
+
+Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. These projects need to be deployed on **Netlify Functions**. Based on the `netlify.toml` file mentioned above, add the following configuration:
+
+```toml title="netlify.toml"
+[build]
+  publish = "dist"
+  command = "modern deploy"
+
+[functions]
+  directory = ".netlify/functions"
+  node_bundler = "none"
+  included_files = [".netlify/functions/**"]
+
+```
+
+:::info
+
+1. Currently, Modern.js does not support deployment on Netlify Edge Functions. We will support it in future versions.
+2. You can refer to the [deployment project example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+
+:::
+
+### Monorepo
+
+:::info
+The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#pure-front-end-project-1) to deploy.
+:::
+
+For Monorepo projects, in addition to building our current project, you also need to build other sub-projects in the repository that the current project depends on.
+
+We take a pnpm Monorepo repository as an example and deploy the Monorepo project on Netlify.
+
+Assuming the directory structure of the Monorepo repository is as follows:
+
+```
+.
+├── packages
+│   ├── app
+│   └── app-dep1
+├── package.json
+├── pnpm-lock.yaml
+└── pnpm-workspace.yaml
+```
+
+You need to configure Base directory on the netlify platform as `packages/app`:
+
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/netlify-monorepo-basedir.png?x-resource-account=public" />
+
+Add the following script in `packages/app/package.json`, before executing the deployment command of the `app` repository, first execute the build of other repositories in the workspace:
+
+```json
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy"
+  }
+}
+```
+
+Configure the build command in `netlify.toml`:
+
+```toml
+[build]
+  publish = "dist"
+  command = "npm run deploy"
+
+[functions]
+  directory = ".netlify/functions"
+  node_bundler = "none"
+  included_files = [".netlify/functions/**"]
+```
+
+Just submit your code and deploy it using the Netlify platform.
+
+## Vercel
+
+Vercel is a deployment platform for modern web applications that provides a rich set of features to support deploying static websites, server-side rendered applications, and more. To deploy on Vercel, you usually need to configure the `vercel.json` file, which you can configure incrementally depending on the complexity of your project.
+
+### Pure Front-end Project
+
+Add the `vercel.json` file to the root directory of the current project:
+
+```bash
+./
+├── src
+├── modern.config.ts
+├── vercel.json
+└── package.json
+```
+
+Add the following content to `vercel.json`:
+
+```json title="vercel.json"
+{
+  "buildCommand": "modern deploy",
+  "outputDirectory": ".vercel/output"
+}
+```
+
+Commit your project to git, select Framework Preset as `Other` on the Vercel platform and deploy.
+
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-framework-preset.png" />
+
+:::info
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+
+:::
+
+### Full Stack Project
+
+Full-stack projects refer to projects that use Custom Web Server, SSR or BFF. These projects need to be deployed on **Vercel Functions**.
+
+In addition to configuring `vercel.json` in the same way as a [pure front-end project](#pure-front-end-project), there are two points to note for full-stack projects:
+
+1. Currently, Modern.js does not support deploying BFF projects on the Vercel platform. We will support it in future versions.
+2. The Node.js version for function execution is determined by the project configuration on the Vercel platform.
+
+:::info
+You can refer to the [deployment project examples](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-ssr).
+
+:::
+
+### Monorepo
+
+:::info
+The following guide is mainly for full-stack projects, for pure CSR projects, just follow [Pure Frontend Project](#pure-front-end-project-1) to deploy.
+:::
+
+For Monorepo projects, in addition to building our current project, you also need to build other sub-projects in the repository that the current project depends on.
+
+We take a pnpm Monorepo repository as an example and deploy the Monorepo project on Vercel.
+
+Assuming the directory structure of the Monorepo repository is as follows:
+
+```
+.
+├── packages
+│   ├── app
+│   └── app-dep1
+├── package.json
+├── pnpm-lock.yaml
+└── pnpm-workspace.yaml
+```
+
+First, you need to configure the **Root Directory** as `packages/app` on the Vercel platform:
+
+<img src="https://sf16-sg.tiktokcdn.com/obj/eden-sg/lmeh7nuptpfnuhd/vercel-root-directory.png" />
+
+Specify Node.js runtime as `20.x`:
+
+```json title="package.json"
+"engines": {
+  "node": "20.x"
+}
+```
+
+Add the following script to `packages/app/package.json` to run `build` command of the other repositories in the workspace before run the `deploy` command for the `app` repository:
+
+```json
+{
+  "scripts": {
+    "build:packages": "pnpm --filter 'app^...' run build",
+    "deploy": "pnpm run build:packages && modern deploy"
+  }
+}
+```
+
+Add the following content to the `packages/app/vercel.json` file:
+
+```json title="vercel.json"
+{
+  "buildCommand": "npm run deploy",
+  "outputDirectory": ".vercel/output"
+}
+```
+
+Just submit your code and deploy it using the Vercel platform.
+
+## Github Pages
+
+If you're creating a GitHub Pages for a repository without a custom domain, the page URL will follow this format: `http://<username>.github.io/<repository-name>`. Therefore, you need to add the following configuration in `modern.config.ts`:
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  //...
+  server: {
+    baseUrl: '/<repository-name>',
+  },
+  output: {
+    assetPrefix: '/<repository-name>',
+  },
+});
+```
+
+GitHub Pages supports two deployment ways: branch deployment or GitHub Actions deployment.
+
+For branch deployment, follow these steps:
+
+1. In the GitHub repository, navigate to Settings > Pages > Source > Deploy from a branch
+2. Install the `gh-pages` as devDependency
+3. Add the following script to `package.json`
+
+```
+"scripts": {
+  //...
+  "deploy:gh-pages": "MODERNJS_DEPLOY=ghPages modern deploy && gh-pages -d .output"
+}
+```
+
+4. Run `npm run deploy:gh-pages`
+
+:::info
+
+1. Running `MODERNJS_DEPLOY=ghPages modern deploy` will build the production output for GitHub in the .output directory.
+2. You can refer to the [project](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)
+   :::
+
+For GitHub Actions deployment, select Settings > Pages > Source > GitHub Actions, and add a workflow file to the project. You can refer to the [example](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr).
+
+## Using Self-Built Node.js Server
+
+Typically, we recommend using the built-in Node.js server of Modern.js to deploy applications. It supports hosting both pure frontend and full-stack projects, ensuring consistent performance in both development and production environments.
+
+If your project is purely frontend, you can also deploy the application to the self-built Node.js server. Below is an example of using a Koa server to host the output of a pure frontend project.
+
+For instance, if you have a Node.js server repository, you can copy the output of the project into this repository. The structure would look like this:
+
+```bash
+.
+├── .output
+│   ├── html
+│   └── static
+└── server.js
+```
+
+In `server.js`, assume you have the following code:
+
+```ts title="server.js"
+import Koa from 'koa';
+
+const app = new Koa();
+app.use(async (ctx, next) => {
+  ctx.body = 'Hello Modern.js';
+});
+app.listen(3000);
+```
+
+Now, you can add some code to include the logic for accessing static resources and HTML files in `server.js`. We need to use the `mime-types` package to get the MIME types of static resources, so let's install the dependency first:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command="add mime-types" />
+
+```ts title="server.js"
+const Koa = require('koa');
+const fs = require('fs');
+const path = require('path');
+const mime = require('mime-types');
+
+const app = new Koa();
+app.use(async (ctx, next) => {
+  if (ctx.path.startsWith('/static')) {
+    ctx.type = mime.lookup(ctx.path);
+    ctx.body = fs.createReadStream(
+      path.resolve(__dirname, `.output${ctx.path}`),
+    );
+  } else if (ctx.path === '/') {
+    ctx.type = 'html';
+    ctx.body = fs.createReadStream(
+      path.resolve(__dirname, '.output/html/main/index.html'),
+    );
+  }
+});
+app.listen(3000);
+```
+
+:::note
+The above code is a basic example. Your application might have multiple entry points and require different HTML files for different paths. A custom Node.js server would also involve more complex logic.
+
+Please note that if your project uses Modern.js conventional routing or if you have set up client-side routing with React Router, you must access HTML files through the correct `baseURL`.
+
+In Modern.js, the default `baseURL` is `'/'`. You can configure it by modifying [`server.baseUrl`](/configure/app/server/base-url) in `modern.config.ts`.
+
+:::danger
+For projects with client-side routing, you can never access HTML files through the `/index.html` path.
+:::
+
+## Nginx
+
+Nginx is a high-performance HTTP and reverse proxy server that can handle static files, reverse proxy, load balancing, and other functions. Deploying on Nginx typically requires configuring the `nginx.conf` file.
+
+If your project is a purely front-end project, you can also deploy the application through Nginx. Here is an example of an Nginx configuration to demonstrate how to host the output of a purely front-end project.
+
+```nginx title="nginx.conf"
+# user [user] [group];
+worker_processes 1;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include       mime.types;
+    default_type  application/octet-stream;
+
+    server {
+        listen 8080;
+        server_name localhost;
+
+        location / {
+            # root [projectPath]/.output/html/main;
+            index index.html;
+            try_files $uri $uri/ =404;
+        }
+
+        location /static {
+          # alias [projectPath]/.output/static;
+        }
+    }
+}
+```
+
+In the above configuration, you need to replace `[projectPath]` with your project path and `[user]` and `[group]` with your current user and user group.
+
+You can copy the above configuration into the `nginx.conf` file in the Nginx installation directory and then start the Nginx service. You can also start the configuration file in a specified path using `nginx -c`, in which case you need to ensure that the path configured in the `include` directive is correct.

package/docs/en/guides/basic-features/env-vars.mdx

@@ -0,0 +1,181 @@
+---
+sidebar_position: 7
+---
+
+# Environment Variables
+
+Modern.js provides support for environment variables, including built-in environment variables and custom environment variables.
+
+## Built-in Environment Variables
+
+### ASSET_PREFIX
+
+The current path prefix of the asset, which is a read-only environment variable.
+
+### NODE_ENV
+
+The current execution environment and is a **read-only** environment variable whose have different values under different execution commands:
+
+- `production`: Default value when running `modern build` or `modern serve`.
+- `development`: Default value when running `modern dev`, also the default value in other cases.
+
+### MODERN_ENV
+
+Set the current execution environment manually. In addition to the values in the NODE_ENV, custom environment names are supported here, such as `staging`, `boe`, etc.
+
+:::tip
+MODERN_ENV priority is higher than NODE_ENV.
+
+:::
+
+### MODERN_TARGET
+
+When using `@modern-js/runtime`, Modern.js will automatically inject `MODERN_TARGET` to distinguish between SSR and CSR environments.
+
+You can use `process.env.MODERN_TARGET` to determine the environment and execute appropriate code.
+
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+After the development build, you can see that the SSR and CSR bundles as follows:
+
+```js title="dist/bundles/main.js"
+// SSR bundles
+function App() {
+  if (false) {
+  }
+}
+```
+
+```js title="dist/static/main.js"
+// CSR bundles
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+This can provide different outputs for different environments to ensure that the bundle size is minimized. It can also be convenient to deal with some side effects for different environments.
+
+:::note Dead Code Elimination
+In production environment, minimizers such as Terser and SWC will analyze the code and remove dead code to reduce the bundle size. This process is called "Dead Code Elimination" (DCE).
+
+For example, the code inside the `if (false)` statement will be removed, while the code inside the `if (true)` will be preserved.
+
+If you do not use `process.env.MODERN_TARGET` as described above, the code minimizer may not be able to analyze the dead code, resulting in an increased bundle size.
+
+:::
+
+## Custom Environment Variables
+
+You can specify custom environment variables in both `shell` and `.env` files.
+
+### Via `shell`
+
+Add custom environment variables before the command:
+
+```shell
+REACT_APP_FOO=123 BAR=456 pnpm run dev
+```
+
+### Via `.env` file
+
+Create a `.env` file in the project root and add custom environment variables, which are added to the Node.js process by default, for example:
+
+```bash
+REACT_APP_FOO=123
+BAR=456
+```
+
+The `.env` file follows the following loading rules:
+
+- `.env`: default.
+- `.env.{ MODERN_ENV | NODE_ENV }`: Overrides `.env` for a specific environment.
+
+When you need to use different config according to the environment, you can define environment variables in the `.env` file corresponding to the environment name, and manually set the execution environment when starting the project.
+
+For example, when starting a project with the following command, the `.env` and `.env.staging` will load:
+
+```shell
+MODERN_ENV=staging pnpm run dev
+```
+
+## Using Environment Variables
+
+### Convention Names
+
+`NODE_ENV` can be used directly in front-end code. In addition, custom environment variables starting with `MODERN_` can also be used directly in code.
+
+For Example:
+
+```js
+if (process.env.NODE_ENV === 'development') {
+  // do something
+}
+```
+
+After executing the `pnpm run dev`, you can see the following bundle:
+
+```js
+if (true) {
+  // do something
+}
+```
+
+In custom HTML templates, you can also use such environment variables directly. For example, in `config/html/head.html`:
+
+```html
+<meta name="test" content="<process.env.NODE_ENV>" />
+```
+
+### Any Other Names
+
+If you need to use environment variables with any other names in your code, you can configure them in [`source.globalVars`](/configure/app/source/global-vars). For example:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    globalVars: {
+      'process.env.VERSION': process.env.VERSION,
+    },
+  },
+});
+```
+
+At this point, the `process.env.VERSION` in the code will be replaced by the value of `VERSION` in the environment variables.
+
+:::note
+`source.globalVars` also supports replacing other expressions or strings with specified values, not limited to environment variables.
+
+:::
+
+## Use Global Replacement
+
+In addition to environment variables, Modern.js also supports replacing variables in code with other values or expressions, which can be used to distinguish between development environment and production environment in code.
+
+For example, converts the expression `TWO` to `1 + 1`:
+
+```ts
+export default {
+  source: {
+    define: {
+      TWO: '1 + 1',
+    },
+  },
+};
+```
+
+```ts
+const foo = TWO;
+
+// ⬇️ Turn into being...
+const foo = 1 + 1;
+```
+
+In most cases, `source.globalVars` is already sufficient to replace variables. But the values passed in by `source.globalVars` will be serialized by JSON by default. So it cannot be replaced like `1 + 1` in the example above, at this time, we need to use [`source.define`](/configure/app/source/define).