From c9ecc92d0558956a8c653c0c1df23b238b16f58c Mon Sep 17 00:00:00 2001 From: Ryan Florence Date: Mon, 18 Sep 2023 15:38:59 -0600 Subject: [PATCH] docs: add troubleshooting to v2 guide --- docs/start/v2.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/start/v2.md b/docs/start/v2.md index 1e8ca6272d1..65ff5ced6e0 100644 --- a/docs/start/v2.md +++ b/docs/start/v2.md @@ -7,6 +7,8 @@ order: 3 All v2 APIs and behaviors are available in v1 with [Future Flags][future-flags]. They can be enabled one at a time to avoid development disruption of your project. After you have enabled all flags, upgrading to v2 should be a non-breaking upgrade. +If you're having trouble see the [Troubleshooting](#troubleshooting) section. + ## `remix dev` For configuration options, see the [`remix dev` docs][v2-dev-config]. @@ -815,7 +817,7 @@ module.exports = { ## `serverModuleFormat` -The default server module output format will be changing from `cjs` to `esm`. +The default server module output format will be changing from `cjs` to `esm`. You can continue to use CJS in v2, many dependencies in your app might not be compatible with ESM. In your `remix.config.js`, you should specify either `serverModuleFormat: "cjs"` to retain existing behavior, or `serverModuleFormat: "esm"`, to opt into the future behavior. @@ -1077,6 +1079,16 @@ module.exports = { }; ``` +## Troubleshooting + +### ESM / CommonJS Errors + +``` +"SyntaxError: Named export '' not found. The requested module '' is a CommonJS module, which may not support all module.exports as named exports." +``` + +Please see the [`serverModuleFormat`](#serverModuleFormat) section. + [future-flags]: ./future-flags [remix-config]: ../file-conventions/remix-config [flat-routes]: https://github.com/remix-run/remix/discussions/4482