📚 Docs: Expand on subpath imports

[borisghidaglia]

What is the improvement or update you wish to see?

A more elaborate example of using subpath imports.

Wrote my experience below. If it is not a skill issue, I think it would be worth adding!

Thanks and have a nice day/evening,

Boris

Is there any context that might help us understand?

Starting from the current raw pnpm dlx create-turbo@latest install and following the Crafting your repository part of the doc, at one point subpath imports are mentioned.

Currently, it points to the Node.js doc and to the Use Node.js subpath imports instead of TypeScript compiler paths section of the doc.

But by just adding the recommended imports to the packages/ui/package.json, we can't use subpath imports yet.

{
  "imports": {
    "#*": "./src/*"
  }
}

Indeed, by importing Card from button we get an error: Cannot find module '#card' or its corresponding type declarations.

import { Card } from "#card";

To fix it, we need to add .js, not ideal.

import { Card } from "#card.js";

But then when running pnpm check-types we get into another problem: error TS2210: The project root is ambiguous, but is required to resolve import map entry 'card.js' in file '/Users/boris/Documents/Clients/Scienta/my-turborepo/packages/ui/package.json'. Supply the rootDir compiler option to disambiguate.

So we add rootDir in packages/ui/package.json

  "compilerOptions": {
    ...
    "rootDir": "src"
  },

And if we want to get rid of the .js from above, we have to do:

  "imports": {
    "#*": "./src/*.js"
  },

Does the docs page already exist? Please link to it.

https://turborepo.com/docs/guides/tools/typescript#use-nodejs-subpath-imports-instead-of-typescript-compiler-paths

[borisghidaglia]

Actually I was wrong, doing that passes type checking but doesn't compile.

So I'm still looking for a solution.

[borisghidaglia]

Ok doing this makes it pass the type checking and compilation:

  "imports": {
    "#*": "./src/*.tsx"
  },

But not great as it handles .tsx only

[borisghidaglia]

Now I landed on:

  "imports": {
    "#*.tsx": "./src/*.tsx",
    "#*.ts": "./src/*.ts"
  },

and

import { Card } from "#card.tsx";
import { two } from "#two.ts";

Can't manage to find how to drop file extensions, but that will do for now (it works with nested folders as well).
Still interested in examples though!

[poeck]

You can set multiple entries as fallbacks:

{
  "imports": {
    "#*": [
      "./src/*",
      "./src/*.ts",
      "./src/*.tsx",
      "./src/*.js",
      "./src/*.jsx",
      "./src/*/index.ts",
      "./src/*/index.tsx",
      "./src/*/index.js",
      "./src/*/index.jsx"
    ]
  },
}

which also allows you to import without a file extension:

import { Card } from "#card";
import { two } from "#two";

[lilianakatrina684-a11y]

Hi! I’d like to work on this docs update and open a PR for it. I’ll keep the change small and focused on adding a concrete subpath imports example based on the current guidance, including the file-extension / fallback details that seem easy to miss. If there’s a preferred doc location or example shape, please let me know. Thanks!

[phsd0]

@poeck @lilianakatrina684-a11y @anthonyshew It seems like this approach with fallback arrays isn't correct or part of any specification. It may work in some cases and may not. So I think we shouldn't recommend this in turbo docs.
vitejs/vite#16153 (comment)