diff --git a/website/docs/en/guide/advanced/_meta.json b/website/docs/en/guide/advanced/_meta.json index 88c595ea9..bf6f98a42 100644 --- a/website/docs/en/guide/advanced/_meta.json +++ b/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" ] diff --git a/website/docs/en/guide/advanced/css.mdx b/website/docs/en/guide/advanced/css.mdx index 1167bf8c0..a76e8a4ba 100644 --- a/website/docs/en/guide/advanced/css.mdx +++ b/website/docs/en/guide/advanced/css.mdx @@ -1 +1,15 @@ # CSS + +## CSS Modules + +## Pre-processors + +### Sass + +### Less + +### Stylus + +## PostCSS + +## Tailwind CSS diff --git a/website/docs/en/guide/advanced/node-polyfill.mdx b/website/docs/en/guide/advanced/output-compatibility.mdx similarity index 61% rename from website/docs/en/guide/advanced/node-polyfill.mdx rename to website/docs/en/guide/advanced/output-compatibility.mdx index 741d660ce..06ab09746 100644 --- a/website/docs/en/guide/advanced/node-polyfill.mdx +++ b/website/docs/en/guide/advanced/output-compatibility.mdx @@ -1,7 +1,28 @@ 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. @@ -9,19 +30,15 @@ Normally, we don't need to use Node libs on the browser side. However, it is pos 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. -### 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 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. diff --git a/website/docs/en/guide/advanced/package-json.mdx b/website/docs/en/guide/advanced/package-json.mdx deleted file mode 100644 index 3cc262d59..000000000 --- a/website/docs/en/guide/advanced/package-json.mdx +++ /dev/null @@ -1 +0,0 @@ -# Write package.json diff --git a/website/docs/en/guide/advanced/polyfill.mdx b/website/docs/en/guide/advanced/polyfill.mdx deleted file mode 100644 index b7c0b37fe..000000000 --- a/website/docs/en/guide/advanced/polyfill.mdx +++ /dev/null @@ -1 +0,0 @@ -# Target and Polyfill diff --git a/website/docs/en/guide/advanced/third-party-deps.mdx b/website/docs/en/guide/advanced/third-party-deps.mdx index 814598828..82af2795e 100644 --- a/website/docs/en/guide/advanced/third-party-deps.mdx +++ b/website/docs/en/guide/advanced/third-party-deps.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`. diff --git a/website/docs/en/guide/basic/output-format.mdx b/website/docs/en/guide/basic/output-format.mdx index 9a4cd86ae..a15d037f4 100644 --- a/website/docs/en/guide/basic/output-format.mdx +++ b/website/docs/en/guide/basic/output-format.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? + ### When to use UMD? @@ -124,3 +127,15 @@ export default defineConfig({ ], }); ``` + +## MF + +### What is MF? + +MF stands for Module Federation. + +### When to use MF? + +### How to build a MF library? + +Check out [Advanced - Module Federation](/guide/advanced/module-federation) chapter for more details. diff --git a/website/docs/en/guide/solution.mdx b/website/docs/en/guide/solution.mdx index a6700350a..d23d4f6b9 100644 --- a/website/docs/en/guide/solution.mdx +++ b/website/docs/en/guide/solution.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 */} diff --git a/website/docs/en/guide/solution/preact.mdx b/website/docs/en/guide/solution/preact.mdx new file mode 100644 index 000000000..9cec8c678 --- /dev/null +++ b/website/docs/en/guide/solution/preact.mdx @@ -0,0 +1 @@ +# Preact diff --git a/website/docs/en/guide/start/components/MF.mdx b/website/docs/en/guide/start/components/MF.mdx new file mode 100644 index 000000000..f717324cf --- /dev/null +++ b/website/docs/en/guide/start/components/MF.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). diff --git a/website/docs/en/guide/start/glossary.mdx b/website/docs/en/guide/start/glossary.mdx index f9675607b..69715f152 100644 --- a/website/docs/en/guide/start/glossary.mdx +++ b/website/docs/en/guide/start/glossary.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). + See [Module Federation](https://rsbuild.dev/guide/advanced/module-federation) for more details.