Proposal: JavaScript/TypeScript configuration files (tsp.config.js / tsp.config.ts) for explicit library resolution

[Hajime-san]

Clear and concise description of the problem

Intro

Currently, TypeSpec primarily relies on tspconfig.yaml for configuration. This YAML-based configuration requires TypeSpec to resolve custom linter libraries and dependencies based on string names internally.

This internal resolution process implicitly depends on the existence of a traditional node_modules structure. This creates significant friction and requires workarounds in modern JavaScript runtimes like Deno, which do not create node_modules directories by default.

For example, to use a custom linter in a Deno environment, developers must currently create an explicit workaround involving symbolic links and dummy package.json files within an emulated node_modules structure to satisfy TypeSpec's internal library resolution logic.

Therefore, I propose adding support for JavaScript (tsp.config.js) and TypeScript (tsp.config.ts) configuration files.

This approach, similar to the modern "Flat Config" adopted by ESLint, allows the configuration to be defined as a JavaScript object, enabling the use of standard ESM import statements.

By using import, we delegate library and module resolution to the host JavaScript runtime. This eliminates TypeSpec's need to parse strings and implicitly rely on file system conventions like node_modules.

Example

// tsp.config.ts
import { defineConfig } from "@typespec/compiler";
import bestPractices from "@typespec/best-practices/recommended"; 
import myCoolLinterRule from "./linter.ts";
import openapi3Emitter from "@typespec/openapi3";

export default defineConfig({
  emit: [
    openapi3Emitter,
  ],

  options: {
    "@typespec/openapi3": {
      "emitter-output-dir": "{output-dir}",
      "output-file": "{service-name}.{version}.spec.yaml",
    },
  },

  linter: {
    extends: [
      bestPractices,
      myCoolLinterRule
    ],
  },
});

// linter.ts
import { defineLinter } from "@typespec/compiler";
import { requiredDocRule } from "./rules/required-doc.rule.ts";

export const $linter = defineLinter({
  ...
});

in YAML:

emit:
  - "@typespec/openapi3"

options:
  "@typespec/openapi3":
    emitter-output-dir: "{output-dir}"
    output-file: "{service-name}.{version}.spec.yaml"

linter:
  library:
    - "@typespec/best-practices/recommended"

Benefits and Rationale

True Runtime Agnosticism: By delegating resolution to the host runtime (via import), TypeSpec achieves better compatibility with diverse environments without requiring file system hacks.

Type Safety for TypeScript: Importing a defineConfig helper allows users to write their configuration with full type safety, IntelliSense, and compilation checks. This is especially useful now that runtimes like Node.js 24+ can execute TypeScript files directly.

Simplified Parser: This change reduces the complexity within TypeSpec's compiler, as the need for a custom YAML parser and string-based module resolution logic is diminished or removed for the JS/TS config path.

Dynamic Configuration: Users gain the ability to use standard JavaScript logic (e.g., conditional statements, environment variables) to dynamically generate their configurations.

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[timotheeguerin]

Thanks for the detailed issue!

While not opposed to supporting this I think a few of your points are not really valid

True Runtime Agnosticism

This I feel doesn't really matter as right after we already need to resolve the import on our own inside of TypeSpec so we are just reusing the same logic and being consitent here is important.

Type Safety for TypeScript

This is definitely nice but we currently do validate the config and should give you the type error and completion in the IDE. On top of that we do provide the emitter options in the completion/validation which you wouldn't get here in TypeScript unless each emitter export their own defineOptions. Even then custom reported errors wouldn't be able to show up in the right place unless we start parsing the ts file ourself(completely defeating the point of this IMO)

Simplified Parser

Removing the yaml config is not an option that would break everybody so we still would have to maintain that and from previous point to get a similar diagnostic capability it might require a way more complex parser.

Dynamic Configuration

That one I do agree is a benefit of allow JS/TS

[Hajime-san]

Thank you for the feedback!

While I dug into the source code and experimented to understand the behavior, I admit I hadn't fully considered the complexities of TypeSpec's custom module resolution logic. I also agree that increasing the number of configuration formats adds maintenance overhead, and I certainly believe YAML support should continue.

BTW, I'd like to highlight one more significant benefit about zero-build for local custom libraries and improved team collaboration.

As you may know, both Node.js and Deno (by default) restrict the execution of TypeScript files inside node_modules to prevent ecosystem fragmentation. This behavior is desirable for published packages.

Currently, when mapping a custom library in YAML, TypeSpec's resolution logic scans for package.json or looks into paths analogous to node_modules. Because of the restriction mentioned above, if a developer writes a custom rule in TypeScript, they are forced to include a build step to compile it to JavaScript before TypeSpec can load it.

This process introduces further friction in multi-developer environments. When changes are made to the custom TypeScript library's source files, developers must manually recognize and rerun the separate build step. This is a common source of subtle integration bugs and developer frustration.

[timotheeguerin]

@Hajime-san thanks for this, supporting running decorators and libraries directly from TypeScript has been an old goal that we never got to. With Node.Js supporting out of hte box it will make this much simpler.

As you may know, both Node.js and Deno (by default) restrict the execution of TypeScript files inside node_modules to prevent ecosystem fragmentation. This behavior is desirable for published packages.

I actually didn't know about this restriciton. Are you saying that as TypeSpec we should or shouldn't align to this restriction. Not following the rules set by Node.Js might create some problems down the line.

Can we continue this discussion on this issue #533 or create a new one to revive this.

[Hajime-san]

Thanks!

Are you saying that as TypeSpec we should or shouldn't align to this restriction.

Looking at the feedback again, I realize I overlooked something.

from: #9057 (comment)

This I feel doesn't really matter as right after we already need to resolve the import on our own inside of TypeSpec, so we are just reusing the same logic, and being consistent here is important.

Is this module resolution for .tsp files?
If so, it certainly makes sense that custom module resolution logic would be needed.
OTOH, I found at the official documentation about a custom linter sample.

import {
  type LinterRuleTester,
  createLinterRuleTester,
  createTestRunner,
} from "@typespec/compiler/testing";
import { requiredDocRule } from "./rules/required-doc.rule.js";

describe("required-doc rule", () => {
  let ruleTester: LinterRuleTester;

  beforeEach(async () => {
    const runner = await createTestRunner();
    ruleTester = createLinterRuleTester(runner, requiredDocRule, "@typespec/my-linter");
  });

  it("emit diagnostics when doc is missing for model", async () => {
    await ruleTester.expect(`model Foo {}`).toEmitDiagnostics({
      code: "@typespec/my-linter/no-foo-model",
      message: "Models must be documented.",
    });
  });

  it("should be valid when doc is provided", async () => {
    await ruleTester.expect(`@doc("documentation") model Bar {}`).toBeValid();
  });
});

I believe this sample code is an example of resolving the specifier @typespec/my-linter using ESM rather than its own module resolution.
My proposal is to elevate this to a TypeSpec configuration file.
TypeSpec's own module resolution logic will still be required for .tsp files, but we thought that ESM would be enough to resolve the issue for other Linters and Emitters. Now, if we leave it up to the JavaScript runtime to decide whether a file is under node_modules, TypeSpec will no longer need to care about that.

And I read the issue: #533
Yeah, there are some similarities to this issue. As pointed out, ESM currently does not have a way to clear the module cache. Normally, this is not an issue with a one-shot command, but I agree that it is a bit concerning for long-lived processes like LSP servers.

As for continuing the discussion, I would like to know how many developers are interested in this proposal, so I thought it would be best to continue the discussion in this issue, or to create a new issue after sorting out the issues that have arisen.

[witemple-msft]

I think it could be powerful, and I'd like to consider the use case for a "micro-emitter:"

// tspconfig.tsx
export default tspConfig({
  // ...
  emit: [
    // or so...
    { $onEmit(program) { ef.render(program, <MyComponent />) } },
  ]
});

function MyComponent() {
  const { program } = useTsp();

  const models = /* get models I want to process */;

  return <ay.For each={models}
    {(m) => <ef.SourceFile name={m.name + ".whatever"}>
        <>Do something highly custom here!</>
      </ef.SourceFile>}
  </ay.For>
}

This could make it much easier to generate one-off or custom components from specs without needing the artifice and ceremony of a full NPM package.

[timotheeguerin]

@Hajime-san it is indeed because we need it for .tsp but because of that we also use our own resolution for everything(And we updated to follow exactly node.js ESM resolution to not create confusion). The problem is when you write

import "foo-bar";

foo-bar is a node package but it could either expose a main.tsp or an index.js but we can't know what is the entrypoint until we have resolved where foo-bar is and its package.json

[Hajime-san]

@witemple-msft
Thanks! Yeah, it's interesting that writing in JSX (TSX) could lead to more declarative configuration files.
On the other hand, it's important to note that Node.js does not yet support JSX (TSX).

• JSX Support nodejs/node#56822

@timotheeguerin
Thank you for the details!
Considering that TypeSpec itself is an execution environment, it seems wise to consider module resolution in TypeSpec files (which internally follow the Node.js ESM resolution algorithm) separately from the ESM of the JavaScript runtime in this proposal.
When I submitted this this, I was only considering configuration files, so I hadn't given any thought to module resolution in TypeSpec files. I currently don't have any ideas about what approach to take.

BTW, I am currently proposing a completely different feature to TypeSpec, and I am currently verifying the compiler code locally.
Although this is a separate issue from module resolution, I will let you know if my deeper understanding of the source code leads to any good ideas for module resolution in TypeSpec files.