Remote declaration file

Search Terms

Remote Reference
Remote Declaration
Declaration URL

Suggestion

Being able to reference .d.ts files from a remote location

Use Cases

Reference .d.ts files which can match with import "http://example.com/Component1"

Examples

/// <referance path="http://example.com/Definitions/Component1" />
import "http://example.com/Component1"

Checklist

My suggestion meets these guidelines:

This wouldn't be a breaking change in existing TypeScript/JavaScript code
This wouldn't change the runtime behavior of existing JavaScript code
This could be implemented without emitting different JS based on the types of the expressions
This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
This feature would agree with the rest of TypeScript's Design Goals.

Do you have a specific use-case in mind? Contextualizing what you're running into and why current workflows aren't sufficient would be helpful.

This would be useful when using remote modules via unpkg without npm installation.

Do you have a specific use-case in mind? Contextualizing what you're running into and why current workflows aren't sufficient would be helpful.

I'm developing a client-side library right now and its components are file seperated with es2015 modules.
So i want to be able to import remote modules.

import { Slider } from "http://www.mycompany.com/UIKit/"

And this actually works for me but i can't actively using it since there is a red line under every import and basically its type is any so no reason to use typescript with it. I'm currently switching to babel with @babel/typescript preset so i can edit my code in compile time but i want typescript features in my vscode. I want my project to be free of node_modules folder except compiler as much as possible. I hope this clarifies my use-case.

gotcha; in the meantime you could possibly use path mapping, but I understand why this is less-than-desirable.

Importing remote modules is where the js community is headed. This is a thing in https://deno.land/ and now browsers are natively supporting this via <script type="module">. I would love to see seamless typescript tooling in these scenarios.

I'm new to this repo so i don't really know release cycle. What kinda life cycle these issues have or when we can prototype it ?

Braden Snell (@bradenhs)

Is there going to be anything further on this issue? As Braden Snell (@bradenhs) says, deno is a thing and there is actually an issue open (denoland/deno#1432) for supporting something like this. One suggestion I had was very similar to the one proposed here, which is something like:

/// @ts-defs https://example.com/definitions/mod.d.ts
import "https://example.com/modules/mod.js"

For deno, the suggestion is now // @deno-defs to prevent using the @ts- space, but if it was natively supported, it would be very useful.

I made a solution for it:

Install the types file: yarn add -D @types/Component1
At the project folder, create a declaration file modules.d.ts with content:

module 'http://example.com/Component1' {
  import content = require('Component1');

  export = content
}

enjoy

import everything from 'http://example.com/Component1'

We have to have a local declaration for supporting intelligence

I have a use case for it. In minimal environments you do not want to use npm or lots of files. Assume you want to edit a single JavaScript file (a script doing calls to an API) with Visual Studio Code. If you can reference remote declaration files (e.g. public git repository with the type declaration of that API) you will benefit from better tool support by only adding a comment on top of that file.

I am currently using the new import maps feature in Google Chrome. This allows me to use the following:

import { h, render, Component } from 'preact';
import Router from 'preact-router';

My import map:

<script type="importmap">
      {
        "imports": {
          "preact": "https://unpkg.com/preact@10.0.5/dist/preact.module.js?module",
          "preact-router": "https://unpkg.com/preact-router@3.1.0/dist/preact-router.es.js"
        }
      }
</script>

I only need the node_modules folder for the declaration files to make VS Code happy. I wish there was a way to fetch the declaration files from some url. Maybe adding it to the tsconfig like so?:

"paths": {
      "preact-router": [
        "https://unpkg.com/preact-router@3.1.0/index.d.ts"
      ]
}

This is just an idea but I could get rid of the node_modules folder entirely this way. To ensure compatibility with other browsers that don't support the import maps yet I could easily have a script that replaces imports with the url found in the import map.

I was thinking about creating an extension for VS Code that would fetch the declaration files on the fly but adding a remote path to some config (tsconfig?) sounds even better.

Module Federation could be a great scenario?

I, too, am using import maps (through the SystemJS polyfill) and would love a feature like this. When a library is updated, it gets updated in the import-map and is never yarn/npm installed to node_modules, so it seems like a remote URL would be the best solution for that setup.

A couple of questions, however -

how often would TS check for remote .d.ts file updates?
can the dev force a recheck?
would maybe some checksum hash (in the file itself? as part of the file name?) be helpful in letting TS know that it either doesn't need to download/write the .d.ts file again or that it needs to?

(this is with the assumption that TS downloads a copy of the .d.ts file as a local cache - but maybe TS doesn't need to do that?)

Johannes Drechsler (@JDrechsler)

There's a great codepen plugin for VSCode which can pull JS dependencies via the CDN but it looks like types still need to be downloaded. lostintangent/codeswing#25 should be a usecase for this. Johannes Drechsler (@JDrechsler) what you described in your comment is exactly what i was looking for

Hello all, is there any update on this?

Our use case

We have a React Microfrontend and right now we don't have any type checking/contract testing between Host app and Microfrontend. As a potential solution we are thinking to have a type checking file in both Host and Microfrontend applications. So when we update the Microfrontend props we want to check the remote Host app's props passed down to the Microfrontend in the Microfrontend PR's linting script to see if they match up. Example code:

// This file lives in the Microfrontend app

// These are the props that will be passed down to the Microfrontend from the Host app
import PropsProvidedByHost from 'https://path.to.host.repo/mfeProps.ts';
// These are the props Microfrontend accepting
import PropsAcceptedByMfe from './local/path/to/mfeProps.ts';

(props: PropsProvidedByHost): PropsAcceptedByMfe => props;

So if this file compiles successfully then it means props from Host app provides the minimum required Microfrontend props. This means the new changes will not break the contract between the Host and Microfrontend.

For example this will pass: (props: { id: string }): { id: string } => props;
but this will not: (props: { id: string }): { id: number } => props;

And similarly we'll do the same check when the Host app's props (which are passed down to Microfrontend) are changed but this time the remote type file will be the Microfrontend's props type file. Example type checking:

// This file lives in the Host app

// These are the props that will be passed to the Microfrontend from the Host app
import PropsProvidedByHost from './local/path/to/mfeProps.ts';
// These are the props Microfrontend accepting
import PropsAcceptedByMfe from 'https://path.to.host.repo/mfeProps.ts';

// if this passes then props from Host app provides the minimum required Microfrontend props
(props: PropsProvidedByHost): PropsAcceptedByMfe => props;

Example code

We use Webpack Module Federation with React lazy and Suspense to load Micrfrontend and render in the Host app. Example Host app code:

type MFEProps = {
  id: string;
};

const MFE: LazyExoticComponent<ComponentType<MFEProps>> = lazy(
  loadFederatedModule('mfeScope', './MfeModule', `https://path.to/remoteEntry.js`)
);

export default () => (
    <Suspense fallback={<Loading />}>
      <MFE id="some-id"  />
    </Suspense>
);

Are there any updates regarding this issue ? I'm trying to implement micro-frontends and having the ability to fetch declaration files over network will allow me to be type-safe when using cross-dependencies.

Bahaa (@BahaaZidan)

Deno deals with this partially but afaik on typescript side there is no development so far. Bahaa (@BahaaZidan)

```ts
module 'http://example.com/Component1' {
  import content = require('Component1');

  export = content
}

enjoy

import everything from 'http://example.com/Component1'

Hi ,
I am trying to share common logic via Single-spa utility.Can you please guide me how can i share my common code using this method.Any workig POC link would be great!!

Really Appreciate your help

Hey! I've been dealing with exactly this problem in microfrontend projects - sharing types between independently deployed apps without a monorepo.

I ended up building a small tool for this: ts-remote

The idea is simple:

Builder - generates a consolidated .d.ts from your source, host it anywhere (CDN, static server, etc.)
Fetcher / CLI - downloads and caches remote types by URL
TS Plugin - add to tsconfig.json and types are resolved in IDE automatically

{
  "compilerOptions": {
    "plugins": [{
      "name": "ts-remote",
      "remotes": {
        "my-app": "https://cdn.example.com/types.d.ts"
      }
    }]
  }
}

After that, import { something } from "my-app" just works in the IDE - autocomplete, go-to-definition, type errors, all the usual stuff.

It's not a native TS solution of course, but it covers the most common use case from this issue. Hope it helps someone!

Contributions and feedback are very welcome 🙌

https://www.npmjs.com/package/ts-remote

I have been developing almost exclusively with a zero-bundler, JIT transpilation + native browser ESM imports setup. I use importmap to route specifiers to a CDN.

It's a great development experience because... it's zero setup, instant to start and easy to embed (my backend serves cached JIT transpiled TypeScript sources directly, eliminating the build step and allowing sources to be embedded within the binary. Great for web powered desktop apps and web apps where the maintenance overhead of bundler tooling outweighs the performance benefit).

Basically this;

<script type="importmap">
  {
    "imports": {
      // Can also be a vendored file
      "react": "https://esm.sh/react@18", 
      "react-dom/client": "https://esm.sh/react-dom@18/client"
    }
  }
</script>
<div id="root"></div>
<script type="module" src="./src/app.tsx"></script>

import React from 'react'
import ReactDOM from 'react-dom/client';

function App() {
  return <h1>Hello World!</h1>
}

const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(<App />);

The only issue is I can't get away from npm install because that's the only way to obtain types.

This adds an unnecessary install step (e.g. I have a Go or Rust backend and I still need Node.js). This also adds the weight of node_modules (deps of deps of deps).

I could use pnpm but tooling complexity creep is a thing I'd like to avoid.

Support for remote declaration files in TypeScript's language server means I would have a completely zero setup, bundler-less development environment. Technically, I could build web applications without even having Node.js installed, just the tsgo binary.

It could be something like this in the tsconfig.json

{
  "compilerOptions": {
    "types": ["https://esm.sh/preact@11"]
  }
}

It could also be supported under import statements in existing declaration files.

esm.sh already returns a x-typescript-types header that lets you find declarations. Maybe support for that header plus support for importmap would work?

The details could be ironed out later, the important question is whether the TypeScript team is keen to adopt the concept of remote declaration files.

Navigation Menu

Repository navigation

Remote declaration file #28985

Search Terms

Suggestion

Use Cases

Examples

Checklist

Our use case

Example code

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Remote declaration file #28985

Description

Search Terms

Suggestion

Use Cases

Examples

Checklist

Activity

DanielRosenwasser commented on Dec 12, 2018

saschanaz commented on Dec 13, 2018

kaaninel commented on Dec 13, 2018

DanielRosenwasser commented on Dec 14, 2018

bradenhs commented on Dec 20, 2018

kaaninel commented on Dec 24, 2018

luvies commented on Feb 17, 2019

zheeeng commented on Mar 14, 2019

jsteuer commented on Sep 8, 2019

JDrechsler commented on Nov 13, 2019

naivefun commented on Dec 8, 2020

frehner commented on Jan 4, 2021

jasonwilliams commented on Jan 27, 2021

qmg-akara commented on Jun 4, 2021

Our use case

Example code

BahaaZidan commented on Jun 15, 2021

kaaninel commented on Jun 23, 2021

pixelamit commented on Jul 1, 2021

arkhipovdenis commented on Mar 4, 2026

alshdavid commented on Oct 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions