From a189a4d9e44b1ba3747a9dc133e3760879c43d59 Mon Sep 17 00:00:00 2001 From: Sam Ko Date: Wed, 25 Sep 2024 17:51:23 -0700 Subject: [PATCH] chore(sass): add docs for `implementation` property in `sassOptions` and update `sassOption` types (#70428) ## Why? We currently don't document the `implementation` property for `sassOptions`. Since this is one our maintained properties, we should also update the types for `sassOptions`. - Fixes https://github.com/vercel/next.js/issues/70020 --------- Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com> Co-authored-by: JJ Kasper --- .../05-styling/03-sass.mdx | 52 +++++++++++++++++-- .../05-next-config-js/sassOptions.mdx | 46 ++++++++++++++++ .../05-next-config-js/useLightningcss.mdx | 4 +- packages/next/src/server/config-schema.ts | 9 +++- packages/next/src/server/config-shared.ts | 7 ++- 5 files changed, 107 insertions(+), 11 deletions(-) create mode 100644 docs/02-app/02-api-reference/05-next-config-js/sassOptions.mdx diff --git a/docs/02-app/01-building-your-application/05-styling/03-sass.mdx b/docs/02-app/01-building-your-application/05-styling/03-sass.mdx index 6a8f4ea649c66..4582991c7d0e8 100644 --- a/docs/02-app/01-building-your-application/05-styling/03-sass.mdx +++ b/docs/02-app/01-building-your-application/05-styling/03-sass.mdx @@ -24,16 +24,58 @@ npm install --save-dev sass ### Customizing Sass Options -If you want to configure the Sass compiler, use `sassOptions` in `next.config.js`. +If you want to configure your Sass options, use `sassOptions` in `next.config`. -```js filename="next.config.js" -const path = require('path') +```ts filename="next.config.ts" switcher +import type { NextConfig } from 'next' -module.exports = { +const nextConfig: NextConfig = { sassOptions: { - includePaths: [path.join(__dirname, 'styles')], + additionalData: `$var: red;`, }, } + +export default nextConfig +``` + +```js filename="next.config.js" switcher +/** @type {import('next').NextConfig} */ + +const nextConfig = { + sassOptions: { + additionalData: `$var: red;`, + }, +} + +module.exports = nextConfig +``` + +#### Implementation + +You can use the `implementation` property to specify the Sass implementation to use. By default, Next.js uses the [`sass`](https://www.npmjs.com/package/sass) package. + +```ts filename="next.config.ts" switcher +import type { NextConfig } from 'next' + +const nextConfig: NextConfig = { + sassOptions: { + implementation: 'sass-embedded', + }, +} + +export default nextConfig +``` + +```js filename="next.config.js" switcher +/** @type {import('next').NextConfig} */ + +const nextConfig = { + sassOptions: { + implementation: 'sass-embedded', + }, +} + +module.exports = nextConfig ``` ### Sass Variables diff --git a/docs/02-app/02-api-reference/05-next-config-js/sassOptions.mdx b/docs/02-app/02-api-reference/05-next-config-js/sassOptions.mdx new file mode 100644 index 0000000000000..8c510fb6c625f --- /dev/null +++ b/docs/02-app/02-api-reference/05-next-config-js/sassOptions.mdx @@ -0,0 +1,46 @@ +--- +title: sassOptions +description: Configure Sass options. +--- + +`sassOptions` allow you to configure the Sass compiler. + +```ts filename="next.config.ts" switcher +import type { NextConfig } from 'next' + +const sassOptions = { + additionalData: ` + $var: red; + `, +} + +const nextConfig: NextConfig = { + sassOptions: { + ...sassOptions, + implementation: 'sass-embedded', + }, +} + +export default nextConfig +``` + +```js filename="next.config.js" switcher +/** @type {import('next').NextConfig} */ + +const sassOptions = { + additionalData: ` + $var: red; + `, +} + +const nextConfig = { + sassOptions: { + ...sassOptions, + implementation: 'sass-embedded', + }, +} + +module.exports = nextConfig +``` + +> **Good to know:** `sassOptions` are not typed outside of `implementation` because Next.js does not maintain the other possible properties. diff --git a/docs/02-app/02-api-reference/05-next-config-js/useLightningcss.mdx b/docs/02-app/02-api-reference/05-next-config-js/useLightningcss.mdx index 1b93f3b66490b..4ff8b2aca645f 100644 --- a/docs/02-app/02-api-reference/05-next-config-js/useLightningcss.mdx +++ b/docs/02-app/02-api-reference/05-next-config-js/useLightningcss.mdx @@ -6,7 +6,7 @@ version: experimental Experimental support for using [Lightning CSS](https://lightningcss.dev), a fast CSS bundler and minifier, written in Rust. -```ts filename="next.config.ts" +```ts filename="next.config.ts" switcher import type { NextConfig } from 'next' const nextConfig: NextConfig = { @@ -18,7 +18,7 @@ const nextConfig: NextConfig = { export default nextConfig ``` -```js filename="next.config.js" +```js filename="next.config.js" switcher /** @type {import('next').NextConfig} */ const nextConfig = { experimental: { diff --git a/packages/next/src/server/config-schema.ts b/packages/next/src/server/config-schema.ts index 82eecea40a2c3..5050c01a648d8 100644 --- a/packages/next/src/server/config-schema.ts +++ b/packages/next/src/server/config-schema.ts @@ -602,8 +602,13 @@ export const configSchema: zod.ZodType = z.lazy(() => ) ) .optional(), - // saas option is unknown, use z.any() here - sassOptions: z.record(z.string(), z.any()).optional(), + // sassOptions properties are unknown besides implementation, use z.any() here + sassOptions: z + .object({ + implementation: z.string().optional(), + }) + .catchall(z.any()) + .optional(), serverExternalPackages: z.array(z.string()).optional(), serverRuntimeConfig: z.record(z.string(), z.any()).optional(), skipMiddlewareUrlNormalize: z.boolean().optional(), diff --git a/packages/next/src/server/config-shared.ts b/packages/next/src/server/config-shared.ts index e24637c181fa5..fdd230c75aea0 100644 --- a/packages/next/src/server/config-shared.ts +++ b/packages/next/src/server/config-shared.ts @@ -770,8 +770,11 @@ export interface NextConfig extends Record { */ basePath?: string - /** @see [Customizing sass options](https://nextjs.org/docs/basic-features/built-in-css-support#customizing-sass-options) */ - sassOptions?: { [key: string]: any } + /** @see [Customizing sass options](https://nextjs.org/docs/app/api-reference/next-config-js/sassOptions) */ + sassOptions?: { + implementation?: string + [key: string]: any + } /** * Enable browser source map generation during the production build