diff --git a/nx-dev/feature-doc-viewer/src/lib/doc-viewer.tsx b/nx-dev/feature-doc-viewer/src/lib/doc-viewer.tsx index 3ba1378ae5..06a2da8407 100644 --- a/nx-dev/feature-doc-viewer/src/lib/doc-viewer.tsx +++ b/nx-dev/feature-doc-viewer/src/lib/doc-viewer.tsx @@ -98,26 +98,31 @@ export function DocViewer({ target="_blank" rel="noreferrer" title="Report an issue on GitHub" - className="relative inline-flex items-center rounded-l-md border border-slate-200 bg-white px-4 py-2 text-xs font-medium text-slate-600 focus-within:ring-blue-500 hover:bg-slate-50 focus:z-10 focus:outline-none focus:ring-1 dark:border-slate-700 dark:bg-slate-800/60 dark:text-slate-400 dark:focus-within:ring-sky-500 dark:hover:bg-slate-800" + className={`relative inline-flex items-center rounded-l-md ${ + // If there is no file path for this page then don't show edit button. + document.filePath ? '' : 'rounded-r-md ' + }border border-slate-200 bg-white px-4 py-2 text-xs font-medium text-slate-600 focus-within:ring-blue-500 hover:bg-slate-50 focus:z-10 focus:outline-none focus:ring-1 dark:border-slate-700 dark:bg-slate-800/60 dark:text-slate-400 dark:focus-within:ring-sky-500 dark:hover:bg-slate-800`} > Report an issue - + {document.filePath ? ( + + ) : null} diff --git a/nx-dev/nx-dev/lib/rspack/content/overview.ts b/nx-dev/nx-dev/lib/rspack/content/overview.ts new file mode 100644 index 0000000000..37b638bc4a --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/content/overview.ts @@ -0,0 +1,102 @@ +export const content = ` +The Nx plugin for Rspack. + +[Rspack](https://www.rspack.dev/) is a fast build tool written in [Rust](https://www.rust-lang.org/) that is interoperable with the Webpack ecosystem. + +Why should you use this plugin? + +- Instant dev server start +- Lightning fast Hot-Module Reloading +- _Fast_ builds using Rspack. +- Out-of-the-box support for TypeScript, JSX, CSS, and more. +- Compatible with the Webpack ecosystem. + +Read more about it in the [Rspack documentation](https://www.rspack.dev/). + +## Setting up a new Nx workspace with Rspack + +You can create a new React workspace that uses Rspack using this command: + +\`\`\`shell +npx create-nx-workspace@latest --preset=@nrwl/rspack +\`\`\` + +You will be prompted for a repository name, which will be used for the folder and application name. + +## Add Rspack to an existing workspace + +There are a number of ways to use Rspack in your existing workspace. + + +First, make sure \`@nrwl/rspack\` is installed. + +{% tabs %} +{% tab label="npm" %} +\`\`\`bash +npm i -D @nrwl/rspack@latest +\`\`\` +{% /tab %} +{% tab label="yarn" %} +\`\`\`bash +yarn add -D @nrwl/rspack@latest +\`\`\` +{% /tab %} +{% tab label="pnpm" %} +\`\`\`bash +pnpm add -D @nrwl/rspack@latest +\`\`\` +{% /tab %} +{% /tabs %} + +### Generate a new project using Rspack + +You can generate a [Web](/packages/web) application, and then use the \`@nrwl/rspack:configuration\` generator to configure the build and serve targets. + +Make sure you have the Web plugin installed. + +{% tabs %} +{% tab label="npm" %} +\`\`\`bash +npm i -D @nrwl/web@latest +\`\`\` +{% /tab %} +{% tab label="yarn" %} +\`\`\`bash +yarn add -D @nrwl/web@latest +\`\`\` +{% /tab %} +{% tab label="pnpm" %} +\`\`\`bash +pnpm add -D @nrwl/web@latest +\`\`\` +{% /tab %} +{% /tabs %} + +Then generate the application. + +\`\`\`bash +nx g @nrwl/web:app my-app --style=css +\`\`\` + +Finally, configure Rspack for the new project. + +\`\`\`bash +nx g @nrwl/rspack:configuration --project=my-app +\`\`\` + +### Modify an existing React or Web project to use Rspack + +You can use the \`@nrwl/rspack:configuration\` generator to change your React or Web project to use Rspack. +This generator will modify your project's configuration to use Rspack, and it will also install all the necessary dependencies. + +You can read more about this generator on the [\`@nrwl/rspack:configuration\`](/packages/rspack/generators/configuration) generator page. + +### Initialize Rspack + +If you do not want to create any new projects or convert any existing projects yet, you can still use Nx to install all the necessary dependencies for Rspack. +This, for example, could be useful if you want to set up Rspack manually for a project. + +\`\`\`bash +nx g @nrwl/rspack:init +\`\`\` +`; diff --git a/nx-dev/nx-dev/lib/rspack/content/rspack-config-setup.ts b/nx-dev/nx-dev/lib/rspack/content/rspack-config-setup.ts new file mode 100644 index 0000000000..f58973b1be --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/content/rspack-config-setup.ts @@ -0,0 +1,83 @@ +export const content = ` +# Configure Rspack on your Nx workspace + +You can configure Rspack using a \`rspack.config.js\` file in your project. You can set the path to this file in your \`project.json\` file, in the \`build\` target options: + +\`\`\`json +//... +"my-app": { + "targets": { + //... + "build": { + "executor": "@nrwl/rspack:rspack", + //... + "options": { + //... + "rspackConfig": "apps/my-app/rspack.config.js" + }, + "configurations": { + ... + } + }, + } +} +\`\`\` + +In that file, you can add the necessary configuration for Rspack. You can read more on how to configure Rspack in the [Rspack documentation](https://www.rspack.dev/). + +### Basic configuration for Nx + +You should start with a basic Rspack configuration for Nx in your project, that looks like this: + +\`\`\`js {% fileName="apps/my-app/rspack.config.js" %} +const { composePlugins, withNx } = require('@nrwl/rspack'); + +module.exports = composePlugins(withNx(), (config, { options, context }) => { + // customize Rspack config here + return config; +}); +\`\`\` + +The \`withNx()\` plugin adds the necessary configuration for Nx to work with Rspack. The \`composePlugins\` function allows you to add other plugins to the configuration. + +#### The \`composePlugins\` function + +The \`composePlugins\` function takes a list of plugins and a function, and returns a Rspack \`Configuration\` object. The \`composePlugins\` function is an enhanced version of the Rspack configuration function, which allows you to add plugins to the configuration, and provides you with a function which accepts two arguments: + +1. \`config\`: The Rspack configuration object. +2. An object with the following properties: + - \`options\`: The options passed to the \`@nrwl/rspack:rspack\` executor. + - \`context\`: The context passed of the \`@nrwl/rspack:rspack\` executor. + +This gives you the ability to customize the Rspack configuration as needed, and make use of the options and context passed to the executor, as well. + +### Add configurations for other functionalities + +In addition to the basic configuration, you can add configurations for other frameworks or features. The \`@nrwl/rspack\` package provides plugins such as \`withWeb\` and \`withReact\`. This plugins provide features such as TS support, CSS support, JSX support, etc. You can read more about how these plugins work and how to use them in our [Rspack Plugins guide](/packages/rspack/documents/rspack-plugins). + +You may still reconfigure everything manually, without using the Nx plugins. However, these plugins ensure that you have the necessary configuration for Nx to work with your project. + +## Customize your Rspack config + +For most apps, the default configuration of Rspack is sufficient, but sometimes you need to tweak a setting in your Rspack config. This guide explains how to make a small change without taking on the maintenance burden of the entire Rspack config. + +### Configure Rspack for React projects + +React projects use the \`withReact\` plugin that adds the necessary configuration for React to work with Rspack. You can use this plugin to add the necessary configuration to your Rspack config. + +\`\`\`js {% fileName="apps/my-app/rspack.config.js" %} +const { composePlugins, withNx, withReact } = require('@nrwl/rspack'); + +// Nx plugins for Rspack. +module.exports = composePlugins( + withNx(), + withReact(), + (config, { options, context }) => { + // Update the Rspack config as needed here. + // e.g. config.plugins.push(new MyPlugin()) + return config; + } +); +\`\`\` + +`; diff --git a/nx-dev/nx-dev/lib/rspack/content/rspack-plugin.ts b/nx-dev/nx-dev/lib/rspack/content/rspack-plugin.ts new file mode 100644 index 0000000000..5821736a5b --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/content/rspack-plugin.ts @@ -0,0 +1,76 @@ +export const content = ` +# Rspack plugins + +Nx uses enhanced Rspack configuration files (e.g. \`rspack.config.js\`). These configuration files export a _plugin_ that takes in a rspack +configuration object and returns an updated configuration object. Plugins are used by Nx to add +functionality to the Rspack build. + +This guide contains information on the plugins provided by Nx. For more information on customizing Rspack configuration, refer to the +[Nx Rspack configuration guide](/packages/rspack/documents/rspack-config-setup). + +## withNx + +The \`withNx\` plugin provides common configuration for the build, including TypeScript support and linking workspace libraries (via tsconfig paths). + +### Example + +\`\`\`js +const { composePlugins, withNx } = require('@nrwl/rspack'); + +module.exports = composePlugins(withNx(), (config) => { + // Further customize Rspack config + return config; +}); +\`\`\` + +## withWeb + +The \`withWeb\` plugin adds support for CSS/SASS/Less/Stylus stylesheets, assets (such as images and fonts), and \`index.html\` processing. + +### Options + +#### stylePreprocessorOptions + +Type: \`{ includePaths: string[] }\` + +Options to pass to style preprocessors. \`includePaths\` is a list of paths that are included (e.g. workspace libs with stylesheets). + +### Example + +\`\`\`js +const { composePlugins, withNx, withWeb } = require('@nrwl/rspack'); + +module.exports = composePlugins( + // always pass withNx() first + withNx(), + // add web functionality + withWeb({ + stylePreprocessorOptions: ['ui/src'], + }), + (config) => { + // Further customize Rspack config + return config; + } +); +\`\`\` + +## withReact + +The \`withReact\` plugin adds support for React JSX and [Fast Refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin) +### Example + +\`\`\`js +const { composePlugins, withNx, withReact } = require('@nrwl/rspack'); + +module.exports = composePlugins( + withNx(), // always pass withNx() first + withReact({ + stylePreprocessorOptions: ['ui/src'], + }), + (config) => { + // Further customize Rspack config + return config; + } +); +\`\`\` +`; diff --git a/nx-dev/nx-dev/lib/rspack/pkg.ts b/nx-dev/nx-dev/lib/rspack/pkg.ts new file mode 100644 index 0000000000..8cdf3cafbf --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/pkg.ts @@ -0,0 +1,86 @@ +import { ProcessedPackageMetadata } from '@nrwl/nx-dev/models-package'; + +export const pkg: ProcessedPackageMetadata = { + description: '', + documents: { + '/packages/rspack/documents/overview': { + id: 'overview', + name: 'Overview of the Nx Rspack plugin', + description: + 'The Nx Plugin for Rspack contains executors and generators that support building applications using Rspack.', + file: '', + itemList: [], + isExternal: false, + path: '/packages/rspack/documents/overview', + tags: [], + }, + '/packages/rspack/documents/rspack-plugins': { + id: 'rspack-plugins', + name: 'Rspack plugins', + description: 'Rspack plugins', + file: '', + itemList: [], + isExternal: false, + path: '/packages/rspack/documents/rspack-plugins', + tags: [], + }, + '/packages/rspack/documents/rspack-config-setup': { + id: 'rspack-config-setup', + name: ' How to configure Rspack on your Nx workspace', + description: + 'A guide on how to configure rspack on your Nx workspace, and instructions on how to customize your rspack configuration.', + file: '', + itemList: [], + isExternal: false, + path: '/packages/rspack/documents/rspack-config-setup', + tags: [], + }, + }, + executors: { + '/packages/rspack/executors/rspack': { + description: 'Run rspack build.', + file: 'generated/packages/rspack/executors/rspack.json', + hidden: false, + name: 'rspack', + originalFilePath: '/packages/rspack/src/executors/rspack/schema.json', + path: '/packages/rspack/executors/rspack', + type: 'executor', + }, + '/packages/rspack/executors/dev-server': { + description: 'Serve a web application.', + file: 'generated/packages/rspack/executors/dev-server.json', + hidden: false, + name: 'dev-server', + originalFilePath: '/packages/rspack/src/executors/dev-server/schema.json', + path: '/packages/rspack/executors/dev-server', + type: 'executor', + }, + }, + generators: { + '/packages/rspack/generators/init': { + description: 'Initialize the `@nrwl/rspack` plugin.', + file: 'generated/packages/rspack/generators/init.json', + hidden: false, + name: 'init', + originalFilePath: '/packages/rspack/src/generators/init/schema.json', + path: '/packages/rspack/generators/init', + type: 'generator', + }, + '/packages/rspack/generators/configuration': { + description: 'Add Rspack configuration to a project.', + file: 'generated/packages/rspack/generators/configuration.json', + hidden: false, + name: 'configuration', + originalFilePath: + '/packages/rspack/src/generators/configuration/schema.json', + path: '/packages/rspack/generators/configuration', + type: 'generator', + }, + }, + githubRoot: 'https://github.com/nrwl/nx-labs/tree/main/packages/rspack', + name: 'Rspack', + packageName: '@nrwl/rspack', + path: '', + root: '', + source: '', +}; diff --git a/nx-dev/nx-dev/lib/rspack/schema/executors/dev-server.ts b/nx-dev/nx-dev/lib/rspack/schema/executors/dev-server.ts new file mode 100644 index 0000000000..2286fccd2f --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/schema/executors/dev-server.ts @@ -0,0 +1,30 @@ +export const schema = { + name: 'dev-server', + implementation: + '/packages/rspack/src/executors/dev-server/dev-server.impl.ts', + schema: { + $schema: 'http://json-schema.org/schema', + version: 2, + cli: 'nx', + title: 'Rspack dev-server executor', + description: '', + type: 'object', + properties: { + buildTarget: { + type: 'string', + description: 'The build target for rspack.', + }, + port: { + type: 'number', + description: 'The port to for the dev-server to listen on.', + }, + }, + required: ['buildTarget'], + presets: [], + }, + description: 'Serve a web application.', + aliases: [], + hidden: false, + path: '/packages/rspack/src/executors/dev-server/schema.json', + type: 'executor', +}; diff --git a/nx-dev/nx-dev/lib/rspack/schema/executors/rspack.ts b/nx-dev/nx-dev/lib/rspack/schema/executors/rspack.ts new file mode 100644 index 0000000000..5aa2645449 --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/schema/executors/rspack.ts @@ -0,0 +1,107 @@ +export const schema = { + name: 'rspack', + implementation: '/packages/rspack/src/executors/rspack/rspack.impl.ts', + schema: { + $schema: 'http://json-schema.org/schema', + version: 2, + cli: 'nx', + title: 'Rspack build executor', + description: '', + type: 'object', + properties: { + target: { + type: 'string', + description: 'The platform to target (e.g. web, node).', + enum: ['web', 'node'], + }, + main: { + type: 'string', + description: 'The main entry file.', + }, + outputPath: { + type: 'string', + description: 'The output path for the bundle.', + }, + tsConfig: { + type: 'string', + description: 'The tsconfig file to build the project.', + }, + indexHtml: { + type: 'string', + description: 'The path to the index.html file.', + }, + rspackConfig: { + type: 'string', + description: 'The path to the rspack config file.', + }, + optimization: { + type: 'boolean', + description: 'Enables optimization of the build output.', + }, + sourceMap: { + description: + "Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment.", + default: true, + oneOf: [ + { + type: 'boolean', + }, + { + type: 'string', + }, + ], + }, + assets: { + type: 'array', + description: 'List of static application assets.', + default: [], + items: { + $ref: '#/definitions/assetPattern', + }, + }, + }, + required: ['target', 'main', 'outputPath', 'tsConfig', 'rspackConfig'], + definitions: { + assetPattern: { + oneOf: [ + { + type: 'object', + properties: { + glob: { + type: 'string', + description: 'The pattern to match.', + }, + input: { + type: 'string', + description: + "The input directory path in which to apply 'glob'. Defaults to the project root.", + }, + ignore: { + description: 'An array of globs to ignore.', + type: 'array', + items: { + type: 'string', + }, + }, + output: { + type: 'string', + description: 'Absolute path within the output.', + }, + }, + additionalProperties: false, + required: ['glob', 'input', 'output'], + }, + { + type: 'string', + }, + ], + }, + }, + presets: [], + }, + description: 'Run rspack build.', + aliases: [], + hidden: false, + path: '/packages/rspack/src/executors/rspack/schema.json', + type: 'executor', +}; diff --git a/nx-dev/nx-dev/lib/rspack/schema/generators/configuration.ts b/nx-dev/nx-dev/lib/rspack/schema/generators/configuration.ts new file mode 100644 index 0000000000..08d0a98aff --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/schema/generators/configuration.ts @@ -0,0 +1,67 @@ +export const schema = { + name: 'configuration', + factory: + './src/generators/configuration/configuration#configurationGenerator', + schema: { + $schema: 'http://json-schema.org/schema', + cli: 'nx', + $id: 'Rspack', + title: '', + type: 'object', + properties: { + project: { + type: 'string', + description: 'The name of the project.', + $default: { + $source: 'argv', + index: 0, + }, + 'x-dropdown': 'project', + 'x-prompt': 'What is the name of the project to set up a rspack for?', + 'x-priority': 'important', + }, + main: { + type: 'string', + description: + "Path relative to the workspace root for the main entry file. Defaults to '/src/main.ts'.", + 'x-priority': 'important', + }, + tsConfig: { + type: 'string', + description: + "Path relative to the workspace root for the tsconfig file to build with. Defaults to '/tsconfig.app.json'.", + 'x-priority': 'important', + }, + target: { + type: 'string', + description: + 'Target platform for the build, same as the rspack config option.', + enum: ['node', 'web'], + default: 'web', + }, + devServer: { + type: 'boolean', + description: 'Add a serve target to run a local rspack dev-server', + default: false, + }, + uiFramework: { + type: 'string', + description: 'The UI framework used by the project.', + enum: ['none', 'react'], + }, + style: { + type: 'string', + description: 'The style solution to use.', + enum: ['none', 'css', 'scss', 'less'], + }, + }, + required: ['project'], + }, + description: 'configurationialize the `@nrwl/rspack` plugin.', + aliases: [], + hidden: false, + implementation: + '/packages/rspack/src/generators/configuration/configuration#configurationGenerator.ts', + path: '/packages/rspack/src/generators/configuration/schema.json', + type: 'generator', +}; diff --git a/nx-dev/nx-dev/lib/rspack/schema/generators/init.ts b/nx-dev/nx-dev/lib/rspack/schema/generators/init.ts new file mode 100644 index 0000000000..0aafc9e62f --- /dev/null +++ b/nx-dev/nx-dev/lib/rspack/schema/generators/init.ts @@ -0,0 +1,31 @@ +export const schema = { + name: 'init', + factory: './src/generators/init/init#rspackInitGenerator', + schema: { + $schema: 'http://json-schema.org/schema', + cli: 'nx', + $id: 'Init', + title: '', + type: 'object', + properties: { + uiFramework: { + type: 'string', + description: 'The UI framework used by the project.', + enum: ['none', 'react', 'web'], + }, + style: { + type: 'string', + description: 'The style solution to use.', + enum: ['none', 'css', 'scss', 'less'], + }, + }, + required: [], + }, + description: 'Initialize the `@nrwl/rspack` plugin.', + aliases: [], + hidden: false, + implementation: + '/packages/rspack/src/generators/init/init#rspackInitGenerator.ts', + path: '/packages/rspack/src/generators/init/schema.json', + type: 'generator', +}; diff --git a/nx-dev/nx-dev/pages/packages/index.tsx b/nx-dev/nx-dev/pages/packages/index.tsx index f390f99dfd..589f860ea7 100644 --- a/nx-dev/nx-dev/pages/packages/index.tsx +++ b/nx-dev/nx-dev/pages/packages/index.tsx @@ -38,14 +38,28 @@ export default function Packages({ 'id' ), }, - packages: useMemo( - () => - sortCorePackagesFirst( - filterMigrationPackages(packages), - 'name' - ), - [packages] - ), + packages: useMemo(() => { + const storybookIdx = packages.findIndex((p) => p.name === 'storybook'); + console.log({ packages, storybookIdx }); + const packagesWithRspack = [ + ...packages.slice(0, storybookIdx), + { + description: + 'The Nx Plugin for Rspack contains executors and generators that support building applications using Rspack.', + githubRoot: 'https://github.com/nrwl/nx/blob/master', + name: 'rspack', + packageName: '@nrwl/rspack', + path: '/packages/rspack', + root: '/packages/rspack', + source: '/packages/rspack/src', + }, + ...packages.slice(storybookIdx), + ]; + return sortCorePackagesFirst( + filterMigrationPackages(packagesWithRspack), + 'name' + ); + }, [packages]), }; return ( @@ -96,7 +110,7 @@ export default function Packages({