From be8c8671c937edde64f47df0eba9c920d11fc362 Mon Sep 17 00:00:00 2001 From: Mohsen Azimi Date: Thu, 30 Dec 2021 17:33:58 -0800 Subject: [PATCH] Add JSDoc to config options --- packages/next/server/config-shared.ts | 137 +++++++++++++++++++++++--- 1 file changed, 122 insertions(+), 15 deletions(-) diff --git a/packages/next/server/config-shared.ts b/packages/next/server/config-shared.ts index d7270c1612a872d..a791832e38d220b 100644 --- a/packages/next/server/config-shared.ts +++ b/packages/next/server/config-shared.ts @@ -43,13 +43,56 @@ export interface TypeScriptConfig { tsconfigPath?: string } +export interface WebpackConfigContext { + /** Next.js root directory */ + dir: string + /** Indicates if the compilation will be done in development */ + dev: boolean + /** It's `true` for server-side compilation, and `false` for client-side compilation */ + isServer: boolean + /** The build id, used as a unique identifier between builds */ + buildId: string + config: NextConfigComplete + /** Default loaders used internally by Next.js */ + defaultLoaders: { + /** Default babel-loader configuration */ + babel: any + } + /** Number of total Next.js pages */ + totalPages: number + /** The webpack configuration */ + webpack: any +} + +export interface NextJsWebpackConfig { + ( + /** Existing Webpack config */ + config: any, + context: WebpackConfigContext + ): any +} + export type NextConfig = { [key: string]: any } & { i18n?: I18NConfig | null eslint?: ESLintConfig typescript?: TypeScriptConfig + /** + * Headers allow you to set custom HTTP headers for an incoming request path. + * + * Refer to complete [Headers configuration documentations](https://nextjs.org/docs/api-reference/next.config.js/headers) + */ headers?: () => Promise + + /** + * Rewrites allow you to map an incoming request path to a different destination path. + * + * Rewrites act as a URL proxy and mask the destination path, making it appear the user hasn't changed their location on the site. + * In contrast, redirects will reroute to a new page and show the URL changes + * + * Refer to complete [Rewrites configuration documentations](https://nextjs.org/docs/api-reference/next.config.js/rewrites) + */ rewrites?: () => Promise< | Rewrite[] | { @@ -58,34 +101,98 @@ export type NextConfig = { [key: string]: any } & { fallback: Rewrite[] } > + + /** + * Redirects allow you to redirect an incoming request path to a different destination path. + * + * Redirects are only available on the Node.js environment and do not affect client-side routing. + * + * Refer to complete [Redirects configuration documentations](https://nextjs.org/docs/api-reference/next.config.js/redirects) + */ redirects?: () => Promise + /** + * Webpack 5 is now the default for all Next.js applications. If you did not have custom webpack configuration your application is already using webpack 5. + * If you do have custom webpack configuration you can refer to the [Next.js webpack 5 documentation](https://nextjs.org/docs/messages/webpack5) for upgrading guidance. + */ webpack5?: false + + /** + * Moment.js includes translations for a lot of locales by default. Next.js now automatically excludes these locales by default + * to optimize bundle size for applications using Moment.js. + * + * To load a specific locale use this snippet: + * + * ```js + * import moment from 'moment' + * import 'moment/locale/ja' + * + * moment.locale('ja') + * ``` + * + * You can opt-out of this new default by adding `excludeDefaultMomentLocales: false` to `next.config.js` if you do not want the new behavior, + * do note it's highly recommended to not disable this new optimization as it significantly reduces the size of Moment.js. + */ excludeDefaultMomentLocales?: boolean - webpack?: - | (( - config: any, - context: { - dir: string - dev: boolean - isServer: boolean - buildId: string - config: NextConfigComplete - defaultLoaders: { babel: any } - totalPages: number - webpack: any - } - ) => any) - | null + /** + * Before continuing to add custom webpack configuration to your application make sure Next.js doesn't already support your use-case + * + * Refer to complete [Custom Webpack Config documentation](https://nextjs.org/docs/api-reference/next.config.js/custom-webpack-config) + * + */ + webpack?: NextJsWebpackConfig | null + /** + * By default Next.js will redirect urls with trailing slashes to their counterpart without a trailing slash. + * For example /about/ will redirect to /about. You can configure this behavior to act the opposite way, + * where urls without trailing slashes are redirected to their counterparts with trailing slashes. + * + * Refer to complete [Trailing Slash Configuration](https://nextjs.org/docs/api-reference/next.config.js/trailing-slash) + */ trailingSlash?: boolean + + /** + * Next.js comes with built-in support for environment variables, which allows you to do the following: + * + * - [Use `.env.local` to load environment variables](#loading-environment-variables) + * - [Expose environment variables to the browser by prefixing with `NEXT_PUBLIC_`](#exposing-environment-variables-to-the-browser) + * + * Refer to complete [Environment Variables documentation](https://nextjs.org/docs/api-reference/next.config.js/environment-variables) + */ env?: { [key: string]: string } + /** + * Detonation directory + */ distDir?: string + /** + * The build output directory (defaults to `.next`) is now cleared by default except for the Next.js caches. + */ cleanDistDir?: boolean + /** + * To set up a CDN, you can set up an asset prefix and configure your CDN's origin to resolve to the domain that Next.js is hosted on. + * + * See [CDN Support with Asset Prefix](https://nextjs.org/docs/api-reference/next.config.js/cdn-support-with-asset-prefix) + */ assetPrefix?: string + /** + * By default, `Next` will serve each file in the `pages` folder under a pathname matching the filename. + * If your project uses a custom server, this behavior may result in the same content being served from multiple paths, + * which can present problems with SEO and UX. + * + * To disable this behavior set this option to `false`. + */ useFileSystemPublicRoutes?: boolean + + /** + * Next.js uses a constant id generated at build time to identify which version of your application is being served. + * This can cause problems in multi-server deployments when `next build` is ran on every server. + * In order to keep a static build id between builds you can provide your own build id. + * + * Use this option to provide your own build id. + */ generateBuildId?: () => string | null | Promise + generateEtags?: boolean pageExtensions?: string[] compress?: boolean