Merge branch 'release-next'

contributors.yml

@@ -1,6 +1,7 @@
 - aaronpowell96
 - aaronshaf
 - abereghici
+- adamwathan
 - abotsi
 - accidentaldeveloper
 - achinchen
@@ -276,6 +277,7 @@
 - lili21
 - lionotm
 - liranm
+- lkwr
 - lordofthecactus
 - lpsinger
 - lswest

docs/file-conventions/remix-config.md

@@ -19,7 +19,6 @@ module.exports = {
     });
   },
   serverBuildPath: "build/index.js",
-  serverBuildTarget: "node-cjs",
 };
 ```
 
@@ -103,21 +102,28 @@ either a `.js` or `.ts` file extension.
 ## serverBuildDirectory
 
 <docs-warning>This option is deprecated and will likely be removed in a future
-stable release. Use [`serverBuildPath`][server-build-path] instead.</docs-warning>
+stable release. Use [`serverBuildPath`][server-build-path]
+instead.</docs-warning>
 
 The path to the server build, relative to `remix.config.js`. Defaults to
 "build". This needs to be deployed to your server.
 
 ## serverBuildPath
 
 The path to the server build file, relative to `remix.config.js`. This file
-should end in a `.js` extension and should be deployed to your server.
-
-If omitted, the default build path will be based on your
-[`serverBuildTarget`][server-build-target].
+should end in a `.js` extension and should be deployed to your server. Defaults
+to `"build/index.js"`.
 
 ## serverBuildTarget
 
+<docs-warning>This option is deprecated and will likely be removed in a future
+stable release. Use a combination of [`publicPath`][public-path],
+[`serverBuildPath`][server-build-path], [`serverConditions`][server-conditions],
+[`serverDependenciesToBundle`][server-dependencies-to-bundle]
+[`serverMainFields`][server-main-fields], [`serverMinify`][server-minify],
+[`serverModuleFormat`][server-module-format] and/or
+[`serverPlatform`][server-platform] instead.</docs-warning>
+
 The target of the server build. Defaults to `"node-cjs"`.
 
 The `serverBuildTarget` can be one of the following:
@@ -130,11 +136,22 @@ The `serverBuildTarget` can be one of the following:
 - [`"node-cjs"`][node-cjs]
 - [`"vercel"`][vercel]
 
+## serverConditions
+
+The order of conditions to use when resolving server dependencies' `exports`
+field in `package.json`.
+
 ## serverDependenciesToBundle
 
-A list of regex patterns that determines if a module is transpiled and included in the server bundle. This can be useful when consuming ESM only packages in a CJS build, or when consuming packages with [CSS side-effect imports][css-side-effect-imports].
+A list of regex patterns that determines if a module is transpiled and included
+in the server bundle. This can be useful when consuming ESM only packages in a
+CJS build, or when consuming packages with [CSS side effect
+imports][css-side-effect-imports].
 
-For example, the `unified` ecosystem is all ESM-only. Let's also say we're using a `@sindresorhus/slugify` which is ESM-only as well. Here's how you would be able to consume those packages in a CJS app without having to use dynamic imports:
+For example, the `unified` ecosystem is all ESM-only. Let's also say we're using
+a `@sindresorhus/slugify` which is ESM-only as well. Here's how you would be
+able to consume those packages in a CJS app without having to use dynamic
+imports:
 
 ```ts filename=remix.config.js lines=[8-13]
 /** @type {import('@remix-run/dev').AppConfig} */
@@ -153,6 +170,29 @@ module.exports = {
 };
 ```
 
+If you want to bundle all server dependencies, you can set
+`serverDependenciesToBundle` to `"all"`.
+
+## serverMainFields
+
+The order of main fields to use when resolving server dependencies. Defaults to
+`["main", "module"]` when `serverModuleFormat` is set to `"cjs"`. Defaults to
+`["module", "main"]` when `serverModuleFormat` is set to `"esm"`.
+
+## serverMinify
+
+Whether to minify the server build in production or not. Defaults to `false`.
+
+## serverModuleFormat
+
+The output format of the server build, which can either be `"cjs"` or `"esm"`.
+Defaults to `"cjs"`.
+
+## serverPlatform
+
+The platform the server build is targeting, which can either be `"neutral"` or
+`"node"`. Defaults to `"node"`.
+
 ## watchPaths
 
 An array, string, or async function that defines custom directories, relative to the project root, to watch while running [remix dev][remix-dev]. These directories are in addition to [`appDirectory`][app-directory].
@@ -173,8 +213,14 @@ There are a few conventions that Remix uses you should be aware of.
 <docs-info>[Dilum Sanjaya][dilum-sanjaya] made [an awesome visualization][an-awesome-visualization] of how routes in the file system map to the URL in your app that might help you understand these conventions.</docs-info>
 
 [minimatch]: https://www.npmjs.com/package/minimatch
+[public-path]: #publicpath
 [server-build-path]: #serverbuildpath
-[server-build-target]: #serverbuildtarget
+[server-conditions]: #serverconditions
+[server-dependencies-to-bundle]: #serverdependenciestobundle
+[server-main-fields]: #servermainfields
+[server-minify]: #serverminify
+[server-module-format]: #servermoduleformat
+[server-platform]: #serverplatform
 [arc]: https://arc.codes
 [cloudflare-pages]: https://pages.cloudflare.com
 [cloudflare-workers]: https://workers.cloudflare.com

docs/file-conventions/route-files-v2.md

@@ -315,64 +315,62 @@ Consider these routes:
 
 ```
 routes/
-  _landing.about.tsx
   _landing._index.tsx
+  _landing.about.tsx
   _landing.tsx
   app._index.tsx
   app.projects.tsx
   app.tsx
   app_.projects.$id.roadmap.tsx
 ```
 
-Some, or all of them can be folders holding their own modules inside:
+Some, or all of them can be folders holding their own modules inside.
 
 ```
 routes/
+  _landing._index/
+    route.tsx
+    scroll-experience.tsx
   _landing.about/
-    index.tsx
     employee-profile-card.tsx
     get-employee-data.server.tsx
+    route.tsx
     team-photo.jpg
-  _landing._index/
-    index.tsx
-    scroll-experience.tsx
   _landing/
-    index.tsx
     header.tsx
     footer.tsx
+    route.tsx
   app._index/
-    index.tsx
+    route.tsx
     stats.tsx
   app.projects/
-    index.tsx
-    project-card.tsx
     get-projects.server.tsx
+    project-card.tsx
     project-buttons.tsx
+    route.tsx
   app/
-    index.tsx
     primary-nav.tsx
+    route.tsx
     footer.tsx
   app_.projects.$id.roadmap/
-    index.tsx
+    route.tsx
     chart.tsx
     update-timeline.server.tsx
   contact-us.tsx
 ```
 
-Note that `app/index.tsx` is _not_ the "index route" for `app/`. It is the node module resolution "index module" for the folder `routes/app/`. The index route for `app/` is `app._index/index.tsx`. The only thing that contributes to the route path is the folder name.
+Note that `app/index.tsx` is _not_ the "index route" for `app/`. It is Note's "index module" for the directory `routes/app/`. The index route for `app/` is `app._index/index.tsx`. The only thing that contributes to the route path is the directory name.
 
 ```
 # these are the same route:
 routes/app.tsx
-routes/app/index.tsx
+routes/app/route.tsx
 
 # as are these
 routes/app._index.tsx
-routes/app._index/index.tsx
+routes/app._index/route.tsx
 ```
 
-In other words `_index` has meaning for Remix index routes, `index` has node module resolution meaning and creates index modules.
-
 ## Scaling
 
 Our general recommendation for scale is to make every route a folder and put the modules used exclusively by that route in the folder, then put the shared modules outside of routes folder elsewhere. This has a couple benefits:

docs/guides/styling.md

@@ -400,7 +400,80 @@ export function links() {
 
 ## Tailwind CSS
 
-Perhaps the most popular way to style a Remix application in the community is to use Tailwind CSS. It has the benefits of inline-style collocation for developer ergonomics and is able to generate a CSS file for Remix to import. The generated CSS file generally caps out around 8-10kb, even for large applications. Load that file into the `root.tsx` links and be done with it. If you don't have any CSS opinions, this is a great approach.
+Perhaps the most popular way to style a Remix application in the community is to use [Tailwind CSS][tailwind]. It has the benefits of inline-style collocation for developer ergonomics and is able to generate a CSS file for Remix to import. The generated CSS file generally caps out around 8-10kb, even for large applications. Load that file into the `root.tsx` links and be done with it. If you don't have any CSS opinions, this is a great approach.
+
+There are a couple of options for integrating Tailwind into your Remix application. You can use Remix's built-in support, or integrate Tailwind manually using their CLI.
+
+### Built-in Tailwind Support
+
+<docs-warning>This feature is unstable and currently only available behind a feature flag. We're confident in the use cases it solves but the API and implementation may change in the future.</docs-warning>
+
+First, to enable built-in Tailwind support, set the `future.unstable_tailwind` feature flag in `remix.config.js`.
+
+```js filename=remix.config.js
+/** @type {import('@remix-run/dev').AppConfig} */
+module.exports = {
+  future: {
+    unstable_tailwind: true,
+  },
+  // ...
+};
+```
+
+Then install Tailwind:
+
+```sh
+npm install -D tailwindcss
+```
+
+Initialize a config file:
+
+```sh
+npx tailwindcss init
+```
+
+Now we can tell it which files to generate classes from:
+
+```js filename=tailwind.config.js lines=[3]
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ["./app/**/*.{ts,tsx,jsx,js}"],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+```
+
+Then include the `@tailwind` directives in your CSS. For example, you could create a `tailwind.css` file at the root of your app:
+
+```css filename=app/tailwind.css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+Then add `tailwind.css` to your root route's `links` function:
+
+```tsx filename=app/root.tsx
+import type { LinksFunction } from "@remix-run/node"; // or cloudflare/deno
+
+// ...
+
+import styles from "./tailwind.css";
+
+export const links: LinksFunction = () => [
+  { rel: "stylesheet", href: styles },
+];
+```
+
+With this setup in place, you can also use [Tailwind's functions and directives][tailwind-functions-and-directives] anywhere in your CSS.
+
+Note that if you're also using Remix's [built-in PostCSS support][built-in-post-css-support], the Tailwind PostCSS plugin will be automatically included if it's missing, but you can also choose to manually include the Tailwind plugin in your PostCSS config instead if you'd prefer.
+
+### Manual Tailwind Integration
+
+It's also possible to use Tailwind without leveraging the built-in support by using the `tailwindcss` CLI directly.
 
 First install a couple of dev dependencies:
 
@@ -527,21 +600,75 @@ export const links: LinksFunction = () => {
 
 ## PostCSS
 
-While not built into Remix's compiler, it is straightforward to use PostCSS and add whatever syntax sugar you'd like to your stylesheets, here's the gist of it:
+[PostCSS][postcss] is a popular tool with a rich plugin ecosystem, commonly used to prefix CSS for older browsers, transpile future CSS syntax, inline images, lint your styles and more.
+
+There are a couple of options for integrating PostCSS into your Remix application. You can use Remix's built-in support, or integrate PostCSS manually using their CLI.
+
+### Built-in PostCSS Support
+
+<docs-warning>This feature is unstable and currently only available behind a feature flag. We're confident in the use cases it solves but the API and implementation may change in the future.</docs-warning>
+
+When a PostCSS config is detected, Remix will automatically run PostCSS across all CSS in your project. For example, to use [Autoprefixer][autoprefixer]:
+
+1. Enable built-in PostCSS support by setting the the `future.unstable_postcss` feature flag in `remix.config.js`.
+
+   ```js filename=remix.config.js
+   /** @type {import('@remix-run/dev').AppConfig} */
+   module.exports = {
+     future: {
+       unstable_postcss: true,
+     },
+     // ...
+   };
+   ```
+
+2. Install any desired PostCSS plugins.
+
+   ```sh
+   npm install -D autoprefixer
+   ```
+
+3. Add `postcss.config.js` in the Remix root with configuration for your plugins.
+
+   ```js filename=postcss.config.js
+   module.exports = {
+     plugins: {
+       autoprefixer: {},
+     },
+   };
+   ```
+
+If you're using [Vanilla Extract][vanilla-extract-2], since it's already playing the role of CSS preprocessor, you may want to apply a different set of PostCSS plugins relative to other styles. To support this, you can export a function from `postcss.config.js` which is given a context object that lets you know when Remix is processing a Vanilla Extract file.
+
+```js filename=postcss.config.js
+module.exports = (ctx) => {
+  return ctx.remix?.vanillaExtract
+    ? {
+        // PostCSS plugins for Vanilla Extract styles...
+      }
+    : {
+        // PostCSS plugins for other styles...
+      };
+};
+```
+
+### Manual PostCSS Integration
+
+It's also possible to use PostCSS without leveraging the built-in support. Here's the gist of it:
 
-1. Use `postcss` cli directly alongside Remix
+1. Use the `postcss` CLI directly alongside Remix
 2. Build CSS into the Remix app directory from a styles source directory
 3. Import your stylesheet to your modules like any other stylesheet
 
 Here's how to set it up:
 
-1. Install the dev dependencies in your app:
+1. Install PostCSS along with its CLI and any desired plugins in your app.
 
    ```sh
    npm install -D postcss-cli postcss autoprefixer
    ```
 
-2. Add `postcss.config.js` in the Remix root.
+2. Add `postcss.config.js` in the Remix root with configuration for your plugins.
 
    ```js filename=postcss.config.js
    module.exports = {
@@ -944,11 +1071,17 @@ module.exports = {
 [examples]: https://github.com/remix-run/examples
 [styled-components-issue]: https://github.com/styled-components/styled-components/issues/3660
 [tailwind]: https://tailwindcss.com
+[tailwind-functions-and-directives]: https://tailwindcss.com/docs/functions-and-directives
 [tailwind-intelli-sense-extension]: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss
+[postcss]: https://postcss.org
+[autoprefixer]: https://github.com/postcss/autoprefixer
+[postcss-preset-env]: https://preset-env.cssdb.org
 [esbuild-css-tree-shaking-issue]: https://github.com/evanw/esbuild/issues/1370
 [css modules]: https://github.com/css-modules/css-modules
 [regular-stylesheet-imports]: #regular-stylesheets
 [server-dependencies-to-bundle]: ../file-conventions/remix-config#serverdependenciestobundle
 [css-bundling]: #css-bundling
 [vanilla-extract]: https://vanilla-extract.style
 [sprinkles]: https://vanilla-extract.style/documentation/packages/sprinkles
+[built-in-post-css-support]: #built-in-postcss-support
+[vanilla-extract-2]: #vanilla-extract

integration/css-modules-test.ts

@@ -27,6 +27,8 @@ test.describe("CSS Modules", () => {
               // ensure features don't clash
               unstable_cssModules: true,
               unstable_cssSideEffectImports: true,
+              unstable_postcss: true,
+              unstable_tailwind: true,
               unstable_vanillaExtract: true,
             },
           };