feat: output type definitions, and allow new Docsify(opts) to accept options for ESM usage

.gitignore

@@ -4,6 +4,7 @@
 /_playwright-report
 /_playwright-results
 /lib
+/dist
 /node_modules
 /.husky/_
 

.prettierignore

@@ -4,3 +4,6 @@ lib/
 themes/
 _playwright-*/
 emoji-data.*
+
+# for some reason this is needed in CI, although locally Prettier ignored dist/ already.
+dist/

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
   "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "cSpell.words": ["coverpage"]
+  "cSpell.words": ["coverpage"],
+  "typescript.tsdk": "node_modules/typescript/lib"
 }

package.json

@@ -12,22 +12,37 @@
   "type": "module",
   "// The 'main' and 'unpkg' fields will remain as legacy for backwards compatibility for now. We will add deprectaion warnings to these outputs to give people time to see the warnings in their apps in a non-breaking way, and eventually we can remove the legacy stuff.": "",
   "main": "lib/docsify.js",
+  "types": "dist/core/Docsify.d.ts",
   "unpkg": "lib/docsify.min.js",
   "// We're using the 'exports' field as an override of the 'main' field to provide the new ESM setup. Once we remove legacy 'main', we will remove the 'exports' field and have a simple ESM setup with only a 'main' field.": "",
+  "// These exports require moduleResolution:NodeNext to be enabled in the consumer.": "",
+  "// TODO native ESM (in browsers) does not work yet because prismjs is not ESM and Docsify source imports it as CommonJS": "",
   "exports": {
-    ".": "./src/Docsify.js",
-    "./*": "./*"
+    "./*": "./*",
+    ".": {
+      "types": "./dist/core/Docsify.d.ts",
+      "default": "./src/core/Docsify.js"
+    }
   },
   "files": [
     "lib",
     "themes"
   ],
+  "// Using 'typesVersions' here is the only way we could figure out how to get types working for imports of any subpath without any of the problems other approaches have when not using modeResolution:NodeNext (listed in https://stackoverflow.com/questions/77856692/how-to-publish-plain-jsjsdoc-library-for-typescript-consumers)": "",
+  "typesVersions": {
+    "*": {
+      "src/*": [
+        "dist/*"
+      ]
+    }
+  },
   "scripts": {
     "build:cover": "node build/cover.js",
     "build:css:min": "node build/mincss.js",
     "build:css": "mkdirp lib/themes && node build/css -o lib/themes",
     "build:emoji": "node ./build/emoji.js",
-    "build:js": "cross-env NODE_ENV=production node build/build.js",
+    "build:js": "npm run build:types && cross-env NODE_ENV=production node build/build.js",
+    "build:types": "tsc -p tsconfig.json || true",
     "build:test": "npm run build && npm test",
     "build": "rimraf lib themes && run-s build:js build:css build:css:min build:cover build:emoji",
     "dev": "run-p serve:dev watch:*",

tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ESNext",
+    "lib": ["DOM", "ESNext"],
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "resolveJsonModule": true,
+    "outDir": "dist/"
+  },
+  "include": ["src/**/*.js"],
+  "exclude": [
+    // "./**/*.test.js",
+    // "test/",
+    // "jest.config.js",
+    // "middleware.js",
+    // "playwright.config.js",
+    // "server.configs.js",
+    // "server.js"
+  ]
+}