Experimental TypeScript compiling outside of app directory feedback thread

[timneutkens]

Feedback thread for #22867. If you try out the experimental feature please provide feedback here.

[rick-nu]

I like this! Usage example in my case, running multiple next typescript projects with a shared components folder:

• project1/
  • components/
  • pages/
• project2/
  • components/
  • pages/
• shared/
  • components/
• next.config.js

And then run next dev project1, next dev project2, using components from the shared folder. The experimental feature is required to achieve this.

[MarkiyanPyts]

This is super useful feature, we are building js resolvers that communicate with API routes importing them from npm linked package, without this feature it was not working. Please add it in next releases as out of the box one

[belgattitude]

@timneutkens Thanks for the great work. I've tested it today on an example monorepo

belgattitude/nextjs-monorepo-example#265

Apart from a log regarding babel configuration, all worked fine

I've also benchmarked builds and compared with the implementation I used before (#13542)

With experimental/externalDirs

**FIRST BUILD: 22 seconds **:
(mean ± σ): 9 seconds:

With previous implementation (webpack)

Example of next.config.js overrides

const nextConfig = {
  webpack: function (config, { defaultLoaders }) {
    // This extra config allows to use paths defined in tsconfig
    // @link https://github.com/vercel/next.js/pull/13542
    const resolvedBaseUrl = path.resolve(config.context, '../../');
    config.module.rules = [
      ...config.module.rules,
      {
        test: /\.(tsx|ts|js|jsx|json)$/,
        include: [resolvedBaseUrl],
        use: defaultLoaders.babel,
        exclude: (excludePath) => {
          return /node_modules/.test(excludePath);
        },
      },
    ];
    return config;
  },
};

**FIRST BUILD: 22 seconds **:
(mean ± σ): 9 seconds:

[balazsorban44]

I just used this flag at nextauthjs/next-auth#2631.

I have an app folder in the repo that is a Next.js app. It imports next-auth from the root folder. This gives better DX without needing to compile the source code before installing it with file:, symlinks, or other stuff in the app folder again.

[maapteh]

Works very well in our lerna workspace, before this i had to include locations in tsconfig which made our imports really weird. Now i can just use the symlink feature by importing from shared components package.

ps i accidentally saw this experimental feature, i guess more people will now have our silly hacks to make it work :)

[rafaelcruzazevedo]

And how do you handle absolute imports in the shared components package? Everything I see related to this, always use relative imports

// shared/components/src/index.ts
import Foo from './components/foo'; => import Foo from 'src/components/foo';

And when imported in (for example) project1, when transpiled returns

Module not found: Can't resolve 'src/components/foo'

[maapteh]

Thats just a Typescript feature. In components itself everything stays relative. In your application project1 you refer to it like:

import Foo from '@shared/components/foo';

project1 tsconfig you add paths:

  "compilerOptions": {
    ...
    "baseUrl": "./src",
    "paths": {
      // wherever the components are located!
      "@shared/components/*": ["../../../packages/components/src/*"],
    }

I assume you have some yarn workspace and or lerna setup.

[rafaelcruzazevedo]

Throw the same error

packages
  - ui-components
    - src
      - components
        - foo-component.tsx
        - bar-components.tsx
      - index.ts // <= here all components exported
      
app
  - project1
    - src
  - project2
    - src

I'm using lerna and next-transpile-modules.
And, if i use relative imports in ui-components, everything works incredibly well.
but if use absolute imports, Module not found: Can't resolve ...

for example in packages/ui-components/src/index.ts

export { default as Foo } from './components/foo-component';  // works
export { default as Foo } from 'src/components/foo-component';  // not working

[maapteh]

Whit this new setting you dont need next-transpile-modules. Do you have checkout somewhere?
Everything should stay relative! in components

[belgattitude]

@rafaelcruzazevedo

As @maapteh suggest, you don't need anymore next-transpile-modules and it's a good thing.

Note that without it, you probably need to be a little more strict. All your packages, apps, will need a package.json with a proper name and workspace dependencies. Note with modern package managers like yarn 3 ... lerna can be dropped too in my opinion.

About:

index.ts // <= here all components exported

The barrel is a good thing. Don't forget you'll need to add a specific path for that, look at the example below:

{
  // Extract of a the app
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {

      // Regular path aliases (local to your app):
      "@/components/*": ["./components/*"],

      // Workspace paths (relative to what you put in baseUrl above):
      "@raphael/ui-component/*": ["../../../packages/ui-component/src/*"], 
      "@raphael/ui-component": ["../../../packages/ui-component/src/index"], <- here the barrel

    }
  },
}

If you want more information, check this out: https://github.com/belgattitude/nextjs-monorepo-example.

It might be useful

[zakariamofaddel]

This feature saved me! 🚀

I have a monorepo setup like so:

• packages
  • nextjs-app/
    • components/
    • pages/
    • next.config.js
  • common-ui/
    • components/ (Using styled-components)

When using styled-components in the nextjs-app I first faced classnames mismatches, but solved by using Babel Macros (https://styled-components.com/docs/tooling#babel-macro).
But when importing components (that are built using styled-components) from the common-ui package, I started facing the same mismatch issue again.
I added this experimental feature to my next.config.js and the macros started being applied to the imported components too.

[markdalgleish]

Thanks for this feature! Exactly what I needed today 🙏

[atilafassina]

Hey, awesome work!!!

Playing around with this and other new features, I may have found a little issue:

I believe externalDir is conflicting with the other experimental feature urlImports
Once both are present in the next.config.js the page with the url import throws

Unhandled Runtime Error
ReferenceError: exports is not defined

[floroz]

I am curious as to why this feature doesn't allow the loading of .module.s?css$?

We're migrating our web apps to Next.js within a Monorepo setup, and the only way to load the SCSS files under our /packages is to use the next-transpile-modules.

Seems quite strange that Next.js doesn't offer first-class support for CSS/SCSS modules from external packages?
Why is the externalDir restricted to such files?

[houkanshan]

externalDir only supports .ts for performance reasons. But we can change the css/scss loaders' configuration in a hacky way to make it transpile them.
I wonder what's the current stage of experimental.externalDir, is there any other concerns about not supporting css?

[floroz]

I see, thanks for pointing that out.

I still see a valid argument to improve the ergonomics of adopting Next.js within a monorepo, without having to rely to next-transpile-modules, and without hacky changes to the webpack config.

If the performance is an issue, why not limiting the surface of the modules that are allowed, with a similar interface?

experimental: {
  externalDir: ['@my-org/shared', '@my-org/core']
}

[Nishchit14]

I am importing storybook components (external) to nextjs monorepo. and It's giving an error of global CSS. It's a very needy feature. In most cases, external components would have their own s|css.

[floroz]

I am importing storybook components (external) to nextjs monorepo. and It's giving an error of global CSS. It's a very needy feature. In most cases, external components would have their own s|css.

Right now the only working solution I've found is to either use next-transpile-module, or override yourself the Next.js webpack loader (which is what next-transpile does under the hood).

The ergonomics to access the CSS loader in the Next.js webpack are not great and it often results in some "hacky" code.

It seems the Next.js is not planning to support loading of external S?CSS via the externalDir feature, and like many others, we also have external components with their own styling to import from the monorepo in our Next.js app.

[andrewmclagan]

I see the externalDir feature being very popular if there is ever support for loading of external css/scss files. Without this I assume its not very useful. Surely the most common use-case for this feature is component libraries?

[lucasbasquerotto]

Thanks for the feature, it worked fine for our use case.

Previously we used next-babel-loader that doesn't work from nextjs 11 onwards. After updating to nextjs 12 we used rsync to sync the shared lib folder in the web folder (used by nextjs, while the shared lib is also used in the native folder, and because of this we place it outside the web folder), but the typescript imports were not from an alias and ctrl clicking and going to the file went to the synced file instead of the original file, so we made them non-writable to see an error when trying to save, but then we had to copy the changes and open the original file, which was not desirable, aside from some problems that happened from time to time in which nextjs couldn't import something, probably some conflict with the live sync process, and we had to stop the dev server and remove the .next folder).

Now it's working fine.

Is there an ETA for when this feature will not be experimental anymore? (that is, when it will be production ready)

[landsman]

I was looking for this probably. 👏

I decided to have an external private package with some business logic so I can share that between our Next.js apps and have a nice abstraction without having a mono repo.

I did not find the reason why I should compile Typescript for the package release until I got an error message about unsupported loaders by Next.js.

Thanks for this experimental way.

[Noitidart]

Files outside the nextjs directory, get module not found error if they use a module that's installed only in the subdirectories:

/time.js - does import moment from 'moment';
/web/package.json - has moment installed. this is the nextjs directory

Here is error:

[Noitidart]

Thanks very much, really appreciate the help!

[AndrewRayCode]

I think this is the error I'm struggling with (my Stackoverflow question). I'm trying to load external React components into a Next app. If I rm -rf node_modules in my external folder, then I get the error

Module not found: Can't resolve 'react/jsx-dev-runtime'

in my next app when I import('../external/MyComponent.tsx'). So to me, this means that Next.js is bundling two builds of React in the local site, which doesn't seem right when importing external files. Or am I missing something?

[AndrewRayCode]

Yeah, with this strategy, when I load my site, things are falling over:

Console warnings:

WARNING: Multiple instances of Three.js being imported.
You might have more than one copy of React in the same app

And some surprising error from React:

TypeError: Cannot read properties of null (reading 'useRef')
at ../external-project/node_modules/react/cjs/react.development.js

Not sure what's going on here, but if the external project has overlapping dependencies with the root one, this strategy seems to double include all libraries.

[maapteh]

This is just normal behaviour of any bundler. With externalDir you can have your components in the same monorepo, or in another local repository. So in the past components had to be in your app, now they can be some levels higher.

You can simply refer to this external library using (i read quickly you own both)

"paths": {
      "@foo/bar/*": [
        "../../../external-lib/components/src/*"
      ],

import('@foo/bar/MyComponent.tsx')

That will give you hot reloads. Now versioning is also just common.

If this external lib hardcodes React or React-dom to 17 and the other 17.6 or 18 for example you have to change one of them :) For shared library its common to set only the peer dependency to >= 17 for example and let the app define its version. But thats up to your own strategy. So its not Next which is bugging you but the deps itself.

[AndrewRayCode]

@maapteh unless I'm missing something again, using peerDependencies in the external project doesn't work. Next/webpack still looks for react in the external folder's node_modules, and bundles both versions of React

[1mzino]

module.exports = { experimental: { externalDir: true, }, }

This solves my error of being unable to use external directories in having a common directory in the parent directory with API calls, redux setup etc.

My only issue is that I am unable to use absolute imports,

This works
import _store from '../../common/store'

This doesnt work
import _store from '@common/store'

My tsconfig includes:
"paths": { "@common/*": ["../common/*"] }

[1mzino]

The common folder is located outside the base directory for my nextJS project, (as it is also used by another nextJS app as well as a React Native app). This lead me to use externalDir as I'd receive a module load error without it.

Apologies if I'm overlooking anything, but including the barrel should mean that I must create an index.ts file exporting all modules contained within the "common" directory, to avoid using excessive import statements?

I've gone ahead and tried exporting only the store.ts to test this new absolute path,

my index files looks like (store being a one of the modules in the common directory)
export * from './store',

I've updated the paths to refer to this new index.ts file
"paths": { "@common/*": ["../common/*"], "@common": ["../common/index"] }

I still receive the same error

error - ./pages/_app.tsx:11:0 Module not found: Can't resolve '@common/store'

[belgattitude]

Do you have a ./common/.../package.json ? or is just a directory ?

[1mzino]

Just a directory with bunch of things such as Redux store, reducer, sagas.. etc as well as helper functions and hooks relating to handling state, I should mention that however the common folder is in the same directory of an existing nextjs app, so it looks something like:

./root/common/../

and

./root/package.json

I believe it was intended to be setup as a monorepo, since there is a need for 2 web apps to be maintained alongside eachother making use of the same redux functionalities as well as sagas/api calls etc.

Could it be that since one app is not maintained in its own base directory, the other suffers unintended functionalities due to the presence of a package.json?

./root/common/, webapp1 essentially lives inside the route folder instead of

./root/common
./root/webapp1/package.json etc
./root/webapp2/package.json etc

[belgattitude]

I've never tested that scenario with externalDirs.... so I can't really say if the paths I've sent you would work, with no barrel it would be difficult I guess

next-transpile-modules ?

Or maybe you found out a blind spot / interesting case for externalDirs ?

[firebelley]

I have a similar setup. Setting the baseUrl in the NextJS tsconfig.json to the level of the common folders seems to allow me to import with no problems. My NextJS app is in src/landing and my shared components are in src/app. Changing src/landing/tsconfig.json like so:

{
...
"baseUrl": "../../",
"paths": {
   "@/app/*": ["src/app/*"]
},
...

Allows me to use imports like @/app/ from any component within my NextJS directory. Hard to say right now if this is going to create unintended issues, but so far so good. I hope that helps you out!

[ryanhaticus]

Dynamic imports aren't working for me... is this supported? I need access to window in my external component.

const EtchKit = dynamic(() => import("../../t/src/index"), {
  ssr: false,
});

const Index = () => {
  return <EtchKit />;
};

'Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.

Check the render method of 'ForwardRef(LoadableComponent)'.

[DaviDevMod]

Awesome feature 🚀

If I was to give a suggestion, it would be to document it thoroughly, with a couple of use cases, as the feature will be used in nontrivial setups.

[Ziothh]

My problem

I get a "module not found" error in my nextjs project when running dev.

I get this error when I use a path alias defined in a tsconfig inside a package. Relative imports do work. It's like the loader doesn't see my compilerOptions.path setting inside the package-scoped tsconfig.

I'm using pnpm workspaces. But I'm pretty sure the same error would occur when using yarn.

Am I doing something wrong or is using a path alias inside a workspace package simply not supported?
I really like this feature but being able to use a path alias and/or absolute imports would make it perfect

(I also saw that 1mzino: #26420 (comment) has the same problem as me and it isn't solved so I'm posting my issue here.)

Thanks in advance.

The error

error - ../database/config/models.ts:1:0
Module not found: Can't resolve '@models/business/Business.model'
> 1 | import Business from "@models/business/Business.model"
  2 | import Image from "@models/Image.model"
  3 | import Site from "@models/Site.model"
  4 | import User from "@models/user/User.model"

You can see the full console log in this screenshot.

Expected Behavior

I should be able to use a tsconfig path alias inside a pnpm workspace package, defined by a tsconfig inside that package.

To Reproduce

What I'm doing

I'm importing a typeorm DataSource instance in web/pages/api/graphql.ts from a workspace package "@workspace/backend".
This itself imports from a module inside that package via "@models" a path alias, defined inside database/tsconfig.json.

My project structure

• tsconfig.base.json (only used for extending)
• backend/ (pnpm package)
• database/ (pnpm package)
• shared/ (pnpm package)
• web/ (this is the nextjs app)
  • next.config.js
  • tsconfig.json
  • pages/
    • api/
      • graphql.ts
  • ...
• pnpm-workspace.yaml

Every package has a tsconfig.json that extends tsconfig.base.json and a package.json.

My config files

tsconfig.base.json

{
    "compilerOptions": {
        "target": "ES2017",
        "module": "ESNext",
        "lib": ["esnext", "ESNext.AsyncIterable"],
        "allowJs": false,
        "skipLibCheck": true,
        "strict": true,
        "forceConsistentCasingInFileNames": true,
        "noEmit": false,
        "esModuleInterop": true,
        "moduleResolution": "node",
        "resolveJsonModule": true,
        "isolatedModules": true,
        "jsx": "preserve",
        "incremental": true,
        "experimentalDecorators": true,
        "strictPropertyInitialization": false,
        "emitDecoratorMetadata": true,
        "baseUrl": ".",
        "paths": {}
    },
    "include": [""],
    "exclude": ["node_modules", "_*"]
}

web/tsconfig.json

{
    "extends": "../tsconfig.base.json",
    "compilerOptions": {
        "lib": ["dom", "dom.iterable", "esnext"],
        "allowJs": true,
        "skipLibCheck": true,
        "strict": false,
        "forceConsistentCasingInFileNames": true,
        "noEmit": false,
        "incremental": true,
        "esModuleInterop": true,
        "module": "esnext",
        "resolveJsonModule": true,
        "isolatedModules": true,
        "jsx": "preserve",
        "baseUrl": "."
    },
    "include": ["next-env.d.ts", "./**/*.ts", "./**/*.tsx"],
    "exclude": ["node_modules"]
}

database/tsconfig.json

{
    "extends": "../tsconfig.base.json",
    "compilerOptions": {
        "baseUrl": ".",
        "rootDir": ".",
        "paths": {
            "@resolvers/*": ["./resolvers/*"],
            "@models/*": ["./models/*"],
            "@config/*": ["./config/*"]
        }
    },
    "include": ["./**/*.ts"]
}

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
    experimental: {
        externalDir: true,
    },
    reactStrictMode: true,
    webpack: (config, { isServer }) => {
        config.resolve.fallback = { fs: false }

        // Fixes api routes crashing
        config.experiments = {
            topLevelAwait: true,
            // it makes a WebAssembly modules async modules
            syncWebAssembly: true,
            asyncWebAssembly: true,
            layers: true,
        }

        // generate wasm module in ".next/server" for ssr & ssg
        if (isServer) {
            config.output.webassemblyModuleFilename = "./../static/wasm/[modulehash].wasm"
        } else {
            config.output.webassemblyModuleFilename = "static/wasm/[modulehash].wasm"
        }

        return {
            ...config,
        }
    },
}

module.exports = nextConfig

[Ziothh]

Here is a link to a port of my project: https://github.com/Ziothh/nextjs-workspace-alias-issue

[ali-garajian]

I have the exact same issue :/

[PaulPopat]

I have an issue with using CSS files from node_modules. When importing a component from an external directory that is importing a CSS file from node_modules, it fails to compile.

E.G.

import React from "react";
import AComponent from "../../../out-of-project/a-component";

const Page = () => <AComponent>Some stuff</AComponent>;

export default Page;

and have a-component.jsx as

import React from "react";
import "a-node-module/styles.css";

export const AComponent = ({ children }) => <div className="class-from-styles">{children}</div>;

[wyattjoh]

The experimental feature for externalDir is designed to extend the transpiration process for typescript by extending the the Next.js projects TS config to these files/folders/packages outside the directory. Imports will still utilize the standard Node.js package resolution algorithm, but subsequent tsconfig.json files will not be picked up when you run next build, hence the errors about being unable to find the imports.

I’ve created a minimal reproduction for using this feature: https://github.com/wyattjoh/nextjs-extern-directory-example

You’ll notice from the packages/app directory, we import from the package/components directory because we’re using the workspace protocol in the packages/app/package.json file (see https://pnpm.io/workspaces#workspace-protocol-workspace). The node resolution process will allow the packages/components package (referenced as @workspace/components) to import from the packages/shared package (referenced as @workspace/shared). If we were not using the externalDir feature, each of these packages would need to be compiled to JS/TS outputs that were later referenced, but this externalDir feature allows you to import these files without the intermediate compilation.

[eric-burel]

Hi, what's the expected behaviour for "process.env"?

I plan to use this feature to be able to quickly share a small database SDK between a Next app, scripts, and long running APIs. It's currently tied to the Next app so relying heavily on "process.env".
I guess I should expect imported code to behave exactly as if it was part of the Next app code base?

[wyattjoh]

This feature is only related to the Typescript compilation, and does not affect runtime. So long as the code is imported and used, it should have access to the same process object.

[junhoyeo]

If you're using external modules in client-side, you don't have access to process.env nor Next's publicRuntimeConfig(which contains allowlisted environment variables), therefore it's impossible to use such values.

[junhoyeo]

If you're using external modules in client-side, you don't have access to process.env nor Next's publicRuntimeConfig(which contains allowlisted environment variables), therefore it's impossible to use such values.

I resolved this issue by adding the NEXT_PUBLIC prefix to all the environment variables. Now I can access in external modules too 👍

[AndrewRayCode]

With externalDir, if the external library includes React, or any other duplicate dependency from your main project, Next.js bundles two copies/versions of React into every page. Am I missing something or configuring something incorrectly? externalDir doesn't look like a viable solution for this reason

[spikebrehm]

Is externalDir: true still the recommended approach for pnpm monorepos in Next 13? Are there any newer things we should try instead?

[timneutkens]

Yeah this is the right way to go. We're going to enable this by default in Next.js 14 as it might cause breakage 👍

[durchanek]

Is it possible the behaviour of this feature has changed recently? I am using it to share icons from another package inside a monorepo, which includes re-exports like:

export { ContentPasteOutlined as AccountIcon } from '@mui/icons-material';

with 14.2, this no longer works and only this does:

export { default as AccountIcon } from '@mui/icons-material/ContentPasteOutlined';