Skip to content

Latest commit

 

History

History
78 lines (62 loc) · 4.44 KB

README.md

File metadata and controls

78 lines (62 loc) · 4.44 KB
Raw

ts-browser

Run typescript files with imports on the fly. Like ts-node, but for browser.

Perfect fallback solution for environments that are only supposed to host static source files (like GitHub Pages) as well as for prototyping and gradual migration of vanilla js or angular projects to tsx/react page by page.

Usage: (sample project)

<!-- index.html -->
<script type="module">
    import {loadModule} from 'https://klesun.github.io/ts-browser/src/ts-browser.js';
    // language=file-reference
    const entryScriptPath = './index.ts';
    loadModule(entryScriptPath).then(indexModule => {
        return indexModule.default(document.getElementById('composeCont'));
    });
</script>
// index.ts
import {makePanel} from './utils/SomeDomMaker.ts';

export default (composeCont) => {
    composeCont.appendChild(makePanel());
};

You can also use it with .tsx files:

https://github.com/klesun-misc/ts-browser-react-example/blob/master/index.html

https://klesun-misc.github.io/ts-browser-react-example/

<script type="module">
    import {loadModule} from 'https://klesun.github.io/ts-browser/src/ts-browser.js';
    // language=file-reference
    const entryScriptPath = './app.tsx';
    loadModule(entryScriptPath, {
        jsx: 2, // ts.JsxEmit.React
    });
</script>

I highly recommend you to also use the @typescript-eslint/consistent-type-imports eslint rule to make sure that no redundant http requests will be performed for type-only imports

If you are using .tsx and the load speed is more important than compatibility with plain tsc emit for you, then I also suggest to set allowImportingTsExtensions to true in compilerOptions of your tsconfig.json and to install eslint-plugin-import with following configuration:

"import/extensions": ["error", {
  "ts": "always",
  "tsx": "always",
  "js": "always",
  "jsx": "always"
}],

This will enforce .ts/.tsx extensions in your imports allowing the compiler to know exactly what file to fetch instead of probing all possible extensions - that basically reduces the number of http requests by half, especially crucial on cellular network.

The script uses typescriptServices.js to parse ts file for dependencies and transpile it to js.

Each file loads about 10-50 milliseconds. Some basic optimization is applied during compilation, like using web workers and storing compilation results in window.localStorage, not sure if it can be optimised further, would need research.

The behaviour on circular dependencies may be not what you expect: I tried to mimick typescript's behaviour (which allows circular dependencies) by creating a Proxy object for the module which throws errors if you attempt to access a field before module fully loaded. If this appears to be inconsistent, you can file an issue with minimal example - I'll think of a better way to implement circular dependencies then.

There was a similar project once, called typescript-script, but it was last updated 5 years ago, did not manage to get it working, and it does not seem to load dependencies.

If you prefer npm:

npm install ts-browser-klesun

import {loadModule} from './node_modules/ts-browser-klesun/src/ts-browser.js';

(it's called ts-browser-klesun in npm, don't confuse with ts-browser which does a similar job, but by listing dependencies in the html file, not with import-s)