docs: solutions overview / output compatibility (#376)

Co-authored-by: Timeless0911 <[email protected]>

Author: fi3ework

website/docs/en/guide/advanced/_meta.json

@@ -1,11 +1,9 @@
 [
-  "package-json",
   "third-party-deps",
-  "polyfill",
+  "output-compatibility",
+  "dts",
   "css",
   "assets",
-  "dts",
   "module-federation",
-  "node-polyfill",
   "storybook"
 ]

website/docs/en/guide/advanced/css.mdx

@@ -1 +1,15 @@
 # CSS
+
+## CSS Modules
+
+## Pre-processors
+
+### Sass
+
+### Less
+
+### Stylus
+
+## PostCSS
+
+## Tailwind CSS

website/docs/en/guide/advanced/node-polyfill.mdx renamed to website/docs/en/guide/advanced/output-compatibility.mdx

@@ -1,27 +1,44 @@
 import { Steps, SourceCode } from '@theme';
 import { PackageManagerTabs } from '@theme';
 
-# Node Polyfill
+# Output Compatibility
+
+This chapter introduces how to specify which target environment should be supported.
+
+## Syntax Downgrade
+
+By setting [lib.syntax](/config/lib/syntax), you can choose the syntax to which JavaScript and CSS will be downgraded. You can use the query syntax from [Browserslist](https://browsersl.ist/). Rslib also supports common ECMAScript version numbers, such as `ES2015`.
+
+Rslib also supports using a [.browserslistrc](https://github.com/browserslist/browserslist#config-file) file to specify settings. Note that [lib.syntax](/config/lib/syntax) takes precedence over `.browserslistrc`. If both are present, `lib.syntax` will be used.
+
+By default, the syntax is set to `ESNext`, which will only supports only the latest version of mainstream browsers (Chrome / Firefox / Edge / macOS Safari / iOS Safari) or Node.js according to [output.target](/config/rsbuild/output#target).
+
+## Polyfill
+
+Before dealing with compatibility issues, it is recommended that you understand the following background knowledge to better handle related issues. Check out the background knowledge on [syntax transpilation and API polyfill](https://rsbuild.dev/guide/advanced/browser-compatibility#syntax-downgrade-and-api-downgrade).
+
+### Browser
+
+{/* TODO */}
+{/* Implement a Rsbuild polyfill plugin by using core-js-pure */}
+
+### Node.js
 
 :::tip About Node Polyfill
 Normally, we don't need to use Node libs on the browser side. However, it is possible to use some Node libs when the code will run on both the Node side and the browser side, and Node Polyfill provides browser versions of polyfills for these Node libs.
 :::
 
 By using [@rsbuild/plugin-node-polyfill](https://github.com/rspack-contrib/rsbuild-plugin-node-polyfill), Node core libs polyfills are automatically injected into the browser-side, allowing you to use these modules on the browser side with confidence.
 
-## Getting Started
-
-### Install plugin
+#### Set up
 
 Rslib uses [@rsbuild/plugin-node-polyfill](https://github.com/rspack-contrib/rsbuild-plugin-node-polyfill) to provide the Node Polyfill feature.
 
 <PackageManagerTabs command="@rsbuild/plugin-node-polyfill -D" />
 
-### Register plugin
-
 Then add the plugin into the plugins field.
 
-```ts
+```ts title="rslib.config.ts"
 import { defineConfig } from '@rslib/core';
 import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';
 
@@ -31,7 +48,7 @@ export default defineConfig({
 });
 ```
 
-### Setup
+#### Configurations
 
 - For projects with `bundle` enabled, the Node Polyfill will be injected and included in the output.
 - For projects with `bundle` disabled, polyfills are not injected into the output by default. To avoid inlining the polyfill in every module. The modules are externalized and need to be added to dependencies manually, follow these steps:
@@ -41,6 +58,4 @@ export default defineConfig({
 
   With the following steps, every usage of the polyfill module will be replaced by the corresponding module in the `externals` field. Checkout the <SourceCode href="https://github.com/web-infra-dev/rslib/blob/main/tests/integration/node-polyfill/bundle-false/rslib.config.ts" /> of the example for more details.
 
-## Configurations
-
 Check out the documentation of [@rsbuild/plugin-node-polyfill](https://github.com/rspack-contrib/rsbuild-plugin-node-polyfill), all the configurations are applicable for Rslib.

website/docs/en/guide/advanced/package-json.mdx

@@ -1,4 +1,4 @@
-# Handle Third-party Dependencies
+# Handle Third-Party Dependencies
 
 Generally, third-party dependencies required by a project can be installed via the `install` command in the package manager. After the third-party dependencies are successfully installed, they will generally appear under `dependencies` and `devDependencies` in the project `package.json`.
 

website/docs/en/guide/advanced/polyfill.mdx

@@ -1,6 +1,7 @@
 import ESM from '../start/components/ESM.mdx';
 import CJS from '../start/components/CJS.mdx';
 import UMD from '../start/components/UMD.mdx';
+import MF from '../start/components/MF.mdx';
 
 # Output Format
 
@@ -64,6 +65,8 @@ The community is migrating to ESM, but there are still many projects using CJS.
 
 ## UMD
 
+### What is UMD?
+
 <UMD />
 
 ### When to use UMD?
@@ -124,3 +127,15 @@ export default defineConfig({
   ],
 });
 ```
+
+## MF
+
+### What is MF?
+
+MF stands for Module Federation. <MF />
+
+### When to use MF?
+
+### How to build a MF library?
+
+Check out [Advanced - Module Federation](/guide/advanced/module-federation) chapter for more details.

website/docs/en/guide/advanced/third-party-deps.mdx

@@ -1 +1,27 @@
 # Solution
+
+In this chapter, we will introduce how to use Rslib to development libraries for browser and Node.js. We will also cover how to create libraries for different UI frameworks.
+
+## Browser Target
+
+Rslib outputs code for the browser by default, so no additional configuration is necessary to get started.
+
+When developing a library that runs in the browser, you can package it in both [ESM](/guide/basic/output-format#esm--cjs) and [CJS](/guide/basic/output-format#esm--cjs) formats for integration with application bundlers. Configuring the package [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to ESM output allows for better tree shaking. Additionally, you can create [UMD](/guide/basic/output-format#umd) format output for direct browser use and even generate [Module Federation ](/guide/advanced/module-federation) formats for dynamic loading by other applications. Configure [Browserslist](/config/rsbuild/output#browserslist) according to the target browser support to determine the downgrade syntax of the output, or adding [polyfill](/guide/advanced/output-compatibility) for API compatibility.
+
+When publishing to npm, you can choose not to [minify](/config/rsbuild/output#minify) your code or to minify it while providing a [sourcemap](/config/rsbuild/output#sourcemap) to enhance the debugging experience for users of your library. For styling, you can use [CSS](/guide/advanced/css), or [CSS pre-processors](/guide/advanced/css#preprocessors) like Sass, Less, or Stylus, or apply [PostCSS](/guide/advanced/css#postcss) for CSS post-processing. Tools like [Tailwind CSS](/guide/advanced/css#tailwind-css) can also help in building your styles. Using [CSS modules](/guide/advanced/css#css-modules) to create CSS modules is another option.
+
+In terms of resource management, Rslib handles [static assets](/guide/advanced/assets) used in your code, such as SVG and PNG files. You can also build a component library of [React](/guide/solution/react), [Preact](/guide/solution/preact), or other frameworks, using [Storybook](/guide/advanced/storybook) for UI component development and testing.
+
+Refer to the solutions in this chapter to learn how to use Rslib to develop browser libraries for different frameworks.
+
+{/* TODO: Clarify default behavior */}
+{/* ### Default Behavior */}
+
+## Node.js Target
+
+By setting set [target](/config/rsbuild/output#target) to `"node"` to development libraries for Node.js.
+
+You can create a [pure ESM](/guide/basic/output-format#esm--cjs) package or a [dual package](/guide/basic/output-format#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims) for compatibility and `__dirname` and `__filename` got an optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps), simplifying the configuration.
+
+{/* TODO: Clarify default behavior */}
+{/* ### Default Behavior */}

website/docs/en/guide/basic/output-format.mdx

@@ -0,0 +1 @@
+# Preact

website/docs/en/guide/solution.mdx

@@ -0,0 +1 @@
+Module Federation is an architectural pattern for JavaScript application decomposition (similar to microservices on the server-side), allowing you to share code and resources between multiple JavaScript applications (or micro-frontends).

website/docs/en/guide/solution/preact.mdx

@@ -1,6 +1,7 @@
 import ESM from './components/ESM.mdx';
 import CJS from './components/CJS.mdx';
 import UMD from './components/UMD.mdx';
+import MF from './components/MF.mdx';
 
 # Glossary
 
@@ -22,7 +23,7 @@ Bundleless refers to a development approach that avoids the traditional practice
 
 ## Module Federation
 
-Module Federation is an architectural pattern for JavaScript application decomposition (similar to microservices on the server-side), allowing you to share code and resources between multiple JavaScript applications (or micro-frontends).
+<MF />
 
 See [Module Federation](https://rsbuild.dev/guide/advanced/module-federation) for more details.