can you find in-depth documents on Obsidian-typesc...

Question

can you find in-depth documents on Obsidian-typescript EMS, Module, babel?

Answer 1

Yes. I’m assuming “EMS” means ESM (ECMAScript Modules).

I checked both the files available in this chat and the web. There aren’t any conversation/internal documents currently available to search, but I found a strong set of primary technical references:

Obsidian sample plugin — build architecture: probably the most relevant practical reference. Obsidian’s official sample uses TypeScript source with module: "ESNext", but esbuild bundles it into CommonJS (format: "cjs") for main.js. That source→bundle distinction is important for understanding Obsidian plugins. (GitHub)
TypeScript Modules — Theory: the deepest conceptual treatment of modules, hosts, ESM vs CJS, resolution, and bundlers. (TypeScript)
TypeScript ESM/CJS Interoperability: particularly useful if you're trying to understand default, __esModule, esModuleInterop, Babel-style interop, and why the same import can behave differently under Node/bundlers/transpilers. (TypeScript)
TypeScript Modules Reference: detailed treatment of module, moduleResolution, nodenext, preserve, commonjs, bundler, .mts/.cts, package "type", etc. (TypeScript)
Babel TypeScript transform: explains the crucial difference between Babel and tsc: Babel can strip/transform TypeScript syntax but does not type-check it. (Babel)
Babel ESM → CommonJS transform: especially valuable alongside Obsidian because it explains __esModule, default-import interop, and Babel's importInterop modes. (Babel)
Babel preset-env / modules: useful for understanding when Babel preserves ESM versus converting it to CJS and how that interacts with a bundler. (Babel)

The key Obsidian pipeline is roughly:

TypeScript source using ESM syntax
import { Plugin } from "obsidian"
↓
TypeScript type-checking (module: ESNext)
↓
esbuild bundling + transpilation
↓
CommonJS output (format: cjs)
↓
main.js loaded by Obsidian

So Babel is not part of the standard Obsidian sample-plugin toolchain; esbuild fills much of the transpilation/bundling role. Babel becomes relevant when comparing transformation semantics or when a project explicitly introduces Babel. (GitHub)

If you want, I can go one level deeper and assemble these into a technical reading pack specifically covering Obsidian + TypeScript + ESM/CJS + esbuild + Babel, ordered from fundamentals → advanced interoperability → Obsidian-specific implementation.

Answer 2

Absolutely. I’d build the reading pack around Obsidian → TypeScript → ESM/CJS → esbuild → Babel → interoperability/debugging, rather than studying each technology separately.

1. Start with the actual Obsidian build

The single most useful artifact is Obsidian’s official sample plugin. (GitHub)

Obsidian sample plugin repository
Obsidian esbuild.config.mjs
Obsidian tsconfig.json

Study those two configuration files side-by-side.

The interesting thing is that tsconfig.json says:

json
"module": "ESNext",
"target": "ES2021",
"moduleResolution": "node",
"isolatedModules": true,
"allowSyntheticDefaultImports": true

while esbuild says, conceptually:

js
entryPoints: ["src/main.ts"],
bundle: true,
format: "cjs",
target: "es2021",
outfile: "main.js"

It also marks things such as obsidian, electron, CodeMirror, Lezer and Node built-ins as external dependencies. (GitHub)

That apparent contradiction—

text
TypeScript: ESNext modules

       BUT

esbuild: CommonJS

—is actually the first big concept to understand.

The TypeScript configuration describes how TypeScript should understand your source, while esbuild controls what ultimately gets packaged into the plugin's runtime artifact.

A useful mental model is:

text
src/main.ts
     │
     │ TypeScript syntax + types
     ▼
┌───────────────────────────┐
│ TypeScript compiler model │
│                           │
│ module = ESNext           │
│ target = ES2021           │
│ isolatedModules = true    │
└─────────────┬─────────────┘
              │
              │ source still uses
              │ import / export
              ▼
┌───────────────────────────┐
│          esbuild          │
│                           │
│ bundle = true             │
│ format = cjs              │
│ treeShaking = true        │
│ target = es2021           │
└─────────────┬─────────────┘
              │
              ▼
           main.js
              │
              │ CommonJS bundle
              ▼
           Obsidian

And some dependencies deliberately escape the bundle:

text
import { Plugin } from "obsidian"
               │
               ▼
          ESBUILD
               │
         "obsidian"
         is external
               │
               ▼
       runtime dependency
               │
               ▼
           Obsidian

That distinction between source module syntax, TypeScript's model, bundler resolution, bundle format, and runtime module system explains an enormous percentage of confusing JavaScript tooling behavior.

2. Then read TypeScript's Modules Theory

This is probably the single best deep document I found.

TypeScript — Modules Theory (TypeScript)

Don't treat this as API documentation. It's closer to a small textbook chapter.

Its central idea is:

The module system is ultimately determined by the host.

TypeScript has to model what that host will eventually do. (TypeScript)

That gives you several separate questions:

text
1. What syntax am I writing?
           ↓
      import/export


2. How does TypeScript resolve it?
           ↓
     moduleResolution


3. Does TypeScript transform it?
           ↓
          module


4. Does a bundler process it?
           ↓
    esbuild / Rollup / etc.


5. What does the final JS contain?
           ↓
       ESM or CJS


6. Who executes that JS?
           ↓
 Node / browser / Electron /
       Obsidian host

Do not move on until those six questions feel distinct.

TypeScript's current documentation explicitly emphasizes that ESM/CJS interoperability differs among Node, bundlers, and transpilers, so there isn't one universal set of interop rules. (TypeScript)

3. ESM itself

Learn native ECMAScript modules independently of TypeScript.

The conceptual primitives are:

js
// named export
export const x = 10;

// named import
import { x } from "./a.js";

// default export
export default foo;

// default import
import foo from "./a.js";

// namespace
import * as foo from "./a.js";

// re-export
export { foo } from "./a.js";

// dynamic import
const module = await import("./a.js");

The important thing isn't memorizing syntax.

Understand that ESM has language-level module semantics.

Conceptually:

text
ES module
────────────────────────────

imports
   │
   ├──── binding ────► export
   │
   ├──── binding ────► export
   │
   └──── binding ────► export

Imports aren't simply equivalent to:

js
const foo = someObject.foo;

ESM exports/imports have module semantics including live bindings.

This becomes important once Babel or a bundler tries to reproduce those semantics using CommonJS.

4. CommonJS

Now contrast ESM with CommonJS.

Classic CommonJS:

js
const obsidian = require("obsidian");

module.exports = something;

or:

js
exports.foo = foo;

Conceptually:

text
CommonJS
─────────────────────

require("foo")
      │
      ▼
 execute module
      │
      ▼
 module.exports
      │
      ▼
 JavaScript object/value

Whereas ESM is conceptually closer to:

text
import
   │
   ▼
module loader
   │
   ▼
module graph
   │
   ▼
linked bindings
   │
   ▼
evaluation

That difference is why converting between them isn't quite as trivial as replacing:

js
import x from "x";

with:

js
const x = require("x");

5. The really important document: ESM/CJS Interoperability

After Modules Theory, read this carefully:

TypeScript — ESM/CJS Interoperability (TypeScript)

This is advanced, but extremely relevant.

It explains why:

js
import foo from "foo";

can mean subtly different things depending on whether foo is:

text
Native ESM
     │
     ├── default export
     │
     ▼

CommonJS
     │
     ├── module.exports
     │
     ▼

Babel-generated CommonJS
     │
     ├── __esModule
     ├── exports.default
     │
     ▼

Bundled module

TypeScript's documentation specifically discusses the infamous “double default” problem, __esModule, default imports, named exports, Node's behavior, and bundler/transpiler behavior. (TypeScript)

This is essential background for understanding Babel.

6. `esModuleInterop`

Spend time on this one option:

json
{
  "compilerOptions": {
    "esModuleInterop": true
  }
}

It's much more consequential than its innocent-looking name suggests.

Suppose a CJS library contains:

js
module.exports = function hello() {};

Developers naturally want:

ts
import hello from "library";

But CJS doesn't actually contain:

js
export default hello;

So somebody has to define what that import means.

That "somebody" might be:

text
TypeScript
Babel
Node
esbuild
Webpack
Rollup
another runtime

And historically they haven't all agreed.

The TypeScript documentation recommends esModuleInterop for applications containing CommonJS code, particularly when a third-party transpiler or bundler is producing the actual JavaScript. (TypeScript)

7. `allowSyntheticDefaultImports`

Now revisit Obsidian's configuration:

json
"allowSyntheticDefaultImports": true

That option affects TypeScript's checking, not the underlying module's actual exports.

Conceptually:

text
Reality:

CommonJS package
module.exports = foo


TypeScript allows:

import foo from "package"


             │
             ▼

"Synthetic" default-import interpretation

That's another major lesson:

What TypeScript permits isn't necessarily a description of the JavaScript module's physical structure.

8. `module`

Now read the full module reference.

TypeScript Modules Reference (TypeScript)

Pay particular attention to:

text
module
├── commonjs
├── es2015 / es2020 / esnext
├── node16
├── node18
├── nodenext
└── preserve

One modern option worth understanding is:

json
"module": "preserve"

With preserve, TypeScript can preserve individual ESM imports/exports while also retaining CommonJS-style constructs where they appear. TypeScript describes this as closely reflecting the capabilities of modern bundlers. (TypeScript)

Don't immediately change an Obsidian project's configuration to it, though. Learn what it means first.

9. `moduleResolution`

This is different from module.

It's probably the most common conceptual mistake.

text
module
│
└── What module format/semantics should
    TypeScript model or emit?


moduleResolution
│
└── Given:

    import x from "foo"

    how does TypeScript determine
    what "foo" refers to?

Current TypeScript has resolution modes including:

text
node-style modes

nodenext
node16
etc.

versus

bundler

bundler models behaviors common to modern JavaScript bundlers, including package "exports"/"imports" while allowing conveniences such as extensionless relative imports. (TypeScript)

So:

ts
import { foo } from "./utils";

raises the question:

text
What is "./utils"?

./utils.ts?
./utils.tsx?
./utils.js?
./utils/index.ts?
package?
exports mapping?
something else?

Module resolution answers that question.

10. Read TypeScript's compiler-option guide

Then:

TypeScript — Choosing Compiler Options (TypeScript)

This becomes especially interesting when bundling.

There's a fundamental complication:

text
Some imports
     │
     ▼
bundled by esbuild


Other imports
     │
     ▼
marked external
     │
     ▼
resolved by runtime

That's exactly relevant to Obsidian because its sample esbuild configuration externalizes obsidian, Electron, CodeMirror/Lezer packages and Node built-ins. (GitHub)

TypeScript's guide points out that a single compilation can't simultaneously use one resolution model for bundled imports and another for externalized imports. (TypeScript)

That is a genuinely deep limitation worth understanding.

11. Now bring Babel into the picture

Babel historically played a huge role in establishing the ESM→CJS conventions developers became accustomed to.

Read:

Babel — transform modules CommonJS (Babel)

For example, Babel can take something conceptually like:

js
export default 42;

and represent the result in CommonJS using an exports.default property plus an __esModule marker. (Babel)

That marker:

js
__esModule

is worth researching deeply.

It isn't native ESM syntax.

It's part of the interoperability conventions created by transpiler ecosystems.

12. Babel's `importInterop`

Once you understand __esModule, investigate Babel's:

text
importInterop

in that same CommonJS transform documentation. (Babel)

This gets directly into:

text
"Babel-style module"
        vs
"Node-style CommonJS"
        vs
plain CommonJS

This is where many mysterious errors originate:

text
foo.default is undefined

or:

text
foo is not a function

or:

text
Cannot use import statement outside a module

or:

text
require is not defined

or:

text
Named export not found

These errors often aren't really "TypeScript problems."

They're module-boundary problems.

13. Babel `preset-env`

Then read:

Babel preset-env (Babel)

Concentrate on:

text
targets
modules

The modules option can be:

text
"commonjs"
"amd"
"umd"
"systemjs"
"auto"
false

and false preserves ESM. (Babel)

This teaches an important lesson:

text
Babel does not necessarily convert ESM.

It depends on configuration.

You might have:

text
TypeScript
    │
    ▼
Babel
    │
    │ modules = false
    ▼
ESM preserved
    │
    ▼
Bundler
    │
    ▼
CJS bundle

or:

text
TypeScript
    │
    ▼
Babel
    │
    │ modules = commonjs
    ▼
CommonJS

or simply, as in the standard Obsidian setup:

text
TypeScript source
      │
      ▼
   esbuild
      │
      ▼
    CJS

No Babel required.

14. Understand transpilation vs type checking vs bundling

This distinction is absolutely fundamental.

text
TYPE CHECKING
────────────────────────────
Does this program make sense
according to TypeScript types?

        TypeScript


TRANSPILATION
────────────────────────────
Convert syntax into different JS.

 TypeScript / Babel / esbuild


MODULE RESOLUTION
────────────────────────────
What file/package does "foo" mean?

 TypeScript / Node / bundler


BUNDLING
────────────────────────────
Combine dependency graph into
one/few output artifacts.

 esbuild / Rollup / Webpack


RUNTIME
────────────────────────────
Actually execute resulting JS.

 browser / Node / Electron /
 Obsidian

One tool can occupy multiple boxes.

That's why discussions saying "TypeScript does X" or "Babel does X" can become misleading without specifying which responsibility we're talking about.

15. Now reconsider Obsidian

With that knowledge, the official Obsidian setup becomes much easier to reason about. (GitHub)

You write:

ts
import {
    Plugin,
    Notice,
    WorkspaceLeaf
} from "obsidian";

Your source is written using ESM syntax.

TypeScript sees:

json
"module": "ESNext"

esbuild sees:

js
bundle: true

but also:

js
external: ["obsidian", ...]

and finally:

js
format: "cjs"

Therefore a better architecture diagram is:

text
                     SOURCE
                       │
                       ▼
                ┌─────────────┐
                │ TypeScript  │
                │   .ts       │
                └──────┬──────┘
                       │
                       │ ESM syntax
                       ▼
                ┌─────────────┐
                │   esbuild   │
                └──────┬──────┘
                       │
           ┌───────────┴───────────┐
           │                       │
      bundled code            externals
           │                       │
           │                    obsidian
           │                    electron
           │                    Node APIs
           │                    CodeMirror
           ▼                       │
       tree shake                  │
           │                       │
           ▼                       │
       transform                   │
           │                       │
           └───────────┬───────────┘
                       ▼
                    main.js
                       │
                       │
                  format = CJS
                       │
                       ▼
                Obsidian runtime

That is the architecture I'd keep in your head.

16. Advanced topic: package.json `"type"`

After that, learn:

json
{
  "type": "module"
}

versus:

json
{
  "type": "commonjs"
}

and:

text
.js
.mjs
.cjs

.ts
.mts
.cts

In Node-style environments, file extension and the nearest package.json "type" can participate in deciding whether JavaScript is treated as ESM or CJS. TypeScript's Node-oriented module modes model those rules. (TypeScript)

This is where a filename stops being "just a filename."

17. Advanced topic: module specifiers

Study the difference between:

ts
import x from "./foo";

ts
import x from "./foo.js";

ts
import x from "foo";

ts
import x from "#foo";

These are different categories of module specifiers.

And importantly, TypeScript generally doesn't simply rewrite your module-specifier strings to fix whatever runtime-resolution model you've chosen. (TypeScript)

That's why:

ts
"./foo"

can type-check in one configuration but produce code unsuitable for another host.

18. Advanced topic: package `exports`

Then investigate modern:

json
{
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils.js"
  }
}

and conditional exports such as:

json
{
  "exports": {
    ".": {
      "import": "...",
      "require": "..."
    }
  }
}

Now this:

ts
import foo from "package";

may resolve differently depending on whether the consumer is using:

text
import
require
Node
bundler
specific conditions

TypeScript's bundler resolution mode supports modern package "exports" and "imports" concepts while modeling bundler-style resolution. (TypeScript)

19. Advanced topic: tree shaking

This is especially useful for Obsidian because its esbuild configuration explicitly enables:

js
treeShaking: true

(GitHub)

Start thinking in graphs:

text
main.ts
 │
 ├──── import A ───► a.ts
 │                    │
 │                    └── function used()
 │
 ├──── import B ───► b.ts
 │                    │
 │                    └── function unused()
 │
 └──── import C ───► c.ts

The bundler builds a dependency graph and attempts to remove unreachable/unnecessary code.

This is another reason preserving structured ESM imports long enough for the bundler to analyze them can be useful.

20. Advanced topic: `isolatedModules`

Notice Obsidian's sample has:

json
"isolatedModules": true

(GitHub)

That is not random.

When a transpiler such as esbuild processes individual TypeScript files without performing TypeScript's whole-program type analysis, some TypeScript constructs can become problematic.

isolatedModules makes TypeScript warn about constructs that aren't safe under this kind of per-file transpilation model.

So think:

text
tsc
────────────────────
understands whole TS program
and type graph


esbuild TS transpilation
────────────────────
primarily transforms files
without TypeScript's complete
type-checking model

That is why a common development workflow separates:

text
type checking

from:

text
building

My recommended reading order

If you want to get genuinely strong at this rather than merely fix one configuration, do it in this order:

Phase A — Obsidian

Obsidian sample plugin repository
tsconfig.json
esbuild.config.mjs
Trace src/main.ts → main.js

Phase B — Module fundamentals

TypeScript Modules introduction (TypeScript)
TypeScript Modules Theory (TypeScript)
Native ESM concepts
CommonJS concepts

Phase C — TypeScript

module
moduleResolution
esModuleInterop
allowSyntheticDefaultImports
isolatedModules
nodenext
bundler
preserve
TypeScript Modules Reference (TypeScript)

Phase D — interoperability

TypeScript ESM/CJS Interoperability (TypeScript)
default semantics
__esModule
synthetic defaults
named imports from CJS
dynamic import()

Phase E — Babel

Babel's module transformation
@babel/plugin-transform-modules-commonjs (Babel)
importInterop
Babel preset-env
modules: false
modules: "commonjs"
modules: "auto" (Babel)

Phase F — bundling

esbuild
entry points
dependency graph
bundle
external
format
target
tree shaking
source maps
minification

And finally return to Obsidian's build configuration. You'll understand considerably more of what every line is doing.

The five documents I'd save permanently

If you only keep five tabs/bookmarks, make them:

TypeScript Modules Theory — best conceptual foundation. (TypeScript)
Read Modules Theory

TypeScript ESM/CJS Interoperability — best explanation of why modules become weird. (TypeScript)
Read ESM/CJS Interoperability

TypeScript Modules Reference — detailed reference once you understand the theory. (TypeScript)
Read Modules Reference

Obsidian esbuild configuration — concrete implementation you're actually dealing with. (GitHub)
Read Obsidian esbuild config

Babel CommonJS transform — explains the historical/transpiler side of interoperability. (Babel)
Read Babel CommonJS transform

If you're learning this specifically to develop/debug Obsidian plugins, the next useful step would be to take a real Obsidian TypeScript file and trace one import all the way through TypeScript resolution → esbuild → generated main.js → Obsidian runtime, including exactly what happens to import { Plugin } from "obsidian". That exercise makes the whole module system click much faster than reading another ten docs.

can you find in-depth documents on Obsidian-typesc...

Frage

Gedanke

Antwort

Frage

Gedanke

Antwort

1. Start with the actual Obsidian build

2. Then read TypeScript's Modules Theory

3. ESM itself

4. CommonJS

5. The really important document: ESM/CJS Interoperability

6. `esModuleInterop`

7. `allowSyntheticDefaultImports`

8. `module`

9. `moduleResolution`

10. Read TypeScript's compiler-option guide

11. Now bring Babel into the picture

12. Babel's `importInterop`

13. Babel `preset-env`

14. Understand transpilation vs type checking vs bundling

15. Now reconsider Obsidian

16. Advanced topic: package.json `"type"`

17. Advanced topic: module specifiers

18. Advanced topic: package `exports`

19. Advanced topic: tree shaking

20. Advanced topic: `isolatedModules`

My recommended reading order

The five documents I'd save permanently

Diesen Q&A teilen

Frage

Gedanke

Antwort

Frage

Gedanke

Antwort

1. Start with the actual Obsidian build

2. Then read TypeScript's Modules Theory

3. ESM itself

4. CommonJS

5. The really important document: ESM/CJS Interoperability

6. esModuleInterop

7. allowSyntheticDefaultImports

8. module

9. moduleResolution

10. Read TypeScript's compiler-option guide

11. Now bring Babel into the picture

12. Babel's importInterop

13. Babel preset-env

14. Understand transpilation vs type checking vs bundling

15. Now reconsider Obsidian

16. Advanced topic: package.json "type"

17. Advanced topic: module specifiers

18. Advanced topic: package exports

19. Advanced topic: tree shaking

20. Advanced topic: isolatedModules

My recommended reading order

The five documents I'd save permanently

Diesen Q&A teilen

6. `esModuleInterop`

7. `allowSyntheticDefaultImports`

8. `module`

9. `moduleResolution`

12. Babel's `importInterop`

13. Babel `preset-env`

16. Advanced topic: package.json `"type"`

18. Advanced topic: package `exports`

20. Advanced topic: `isolatedModules`