Design Meeting Notes, 2026-08-25

[DanielRosenwasser]

Import Attributes on Ambient Modules

#63931

• ECMAScript now has stage-3 recognized type attributes on import statements.

  // text has type `string`
  import text from "./file.txt" with { "type": "text" }
  
  // bytes has type `Uint8Array`
  import bytes from "./file.whatever" with { "type": "bytes" }

  • https://github.com/tc39/proposal-import-text
    • stage 3
  • https://github.com/tc39/proposal-import-bytes
    • stage 2.7

• Spec explicitly will allow these, but environments are free to add their own.

  • For example, browsers explicitly support type: "css".

• Last discussed Design Meeting Notes, 9/26/2025 #62615

  • Big question that came up was whether we should resolve to check paths, copy as outputs.
    • Leaned towards no.

• So Support import attributes on ambient modules #63931 adds support for import attributes in ambient modules.

  // Could write:
  declare module "*" with { "type": "text" } {
      const text: string;
      export default text;
  }
  
  declare module "*" with { "type": "bytes" } {
      const bytes: Uint8Array;
      export default bytes;
  }
  
  // For the browser:
  declare module "*" with { "type": "css" } {
      const css: string;
      export default css;
  }

• Idea is that these patterns are actually limited type specifications.

  declare module "./file.something" with { "some-attribute": string } {
      // ...
  }

• We match specifiers against patterns and get the most specific patterns and attribute types.

  • What is most-specific?
  • We use a form of subtype reduction based on the type derived from the import attributes, along with longest specifier matches.
  • What if they "tie"? Mutually exclusive types.
    • First one in the program wins.

• Is the idea that lib.esnext.d.ts and lib.dom.d.ts will have the above import attributes?

  • Yes... maybe?
  • Though it's possible that now you'll accidentally end up with lib.dom.d.ts brought into Node.js context - pretty common unfortunately.
    • True, but you need to explicitly write type: "css".
  • People might already have their own?
    • But these would have a specific type pattern anyway.

• File existence?

  • Something we can extend out to the future.

• File copying from inputs/outputs?

  • This is what happens with JSON on certain resolution modes.
  • Causes all sorts of issues (e.g. importing from package.json).
  • Want to avoid this.

• Merging conflicting declarations?

  • Maybe we can do something a little bit better on ambient module declarations.
  • What about forbidding overlaps?

• Why are these types more capable just allowing unit types?

  • Why allow type: string?

  • Because you might want union types, reduce code.

    declare module "*" with { "type": "md" | "markdown" } {
        // ...
    }

    • Yeah, but you can just write multiple specific modules instead of using a union type. It's duplicative but it's fine.

  • Also, overrides? Unions would have allowed those.

    declare module "*.foo" with { "my-thing": "a" | "b" } {/*base contents*/}
    declare module "*.foo" with { "my-thing": "a" } {/*overrides with more specific type for 'a'*/}
    
    // vs.
    
    declare module "*.foo" with { "my-thing": "a" } {/*base contents*/}
    declare module "*.foo" with { "my-thing": "b" } {/*base contents*/}
    
    // This is now a merge with the first declaration.
    declare module "*.foo" with { "my-thing": "a" } {/*overrides(?) with more specific type for 'a'*/}

  • But lots of problems that can come up with "most specific" lookup.

    • Like what?
      • Part of it is now like overload resolution
      • Hard to diagnose which one is chosen (or not chosen).
      • Also, can mix poorly when types have differing IDs, working with parallel independent checkers.

• Conclusions:

  • 7.1 will have unit-only types, no override behavior for declare module.
  • This PR will not contain lib.d.ts updates, and they may not ship as part of 7.1.
  • Future: revisit the above, plus a flag to make sure that the existence of relative file paths are actually checked when they hit a pattern.

[DanielRosenwasser]

Something Bartek Iwańczuk (@bartlomieju) raised afterwards was that the current semantics of prioritizing standard resolutions over type attributes means that we'll resolve the wrong types for sourceText in the following code.

import sourceText from "./a.js" with { type: "text" };

Gabriela Araujo Britto (@gabritto) and I chatted, and while it's very rare that you'd want an alternative import type from a recognized file type, we'd like to align with the spec.

It does feel like { type: "css" } on an import is a good indicator of what you want, but Andrew Branch (@andrewbranch) asked if the existence of a .d.css.ts implies a user wants a more specific module shape. More broadly, you can imagine an ambient module like

declare module "*.templit" with { type: "myTemplateLang" } {
  declare var render: (props: Record<string, any>) => any;
  export default render;
}

but generate more specific types at build time. That said, I have a hard time imagining that you'd want a type: ... for something your build tooling handles anyway. Maybe you just want a fallback for when a content mapper won't be active?