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 #70020

---------

Co-authored-by: Zack Tanner <1939140+ztanner@users.noreply.github.com>
Co-authored-by: JJ Kasper <jj@jjsweb.site>

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

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.

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: {

packages/next/src/server/config-schema.ts

@@ -602,8 +602,13 @@ export const configSchema: zod.ZodType<NextConfig> = 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(),

packages/next/src/server/config-shared.ts

@@ -770,8 +770,11 @@ export interface NextConfig extends Record<string, any> {
    */
   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