{"id":22539459,"url":"https://github.com/polyforest/jsdoc-tsimport-plugin","last_synced_at":"2025-04-09T21:43:34.272Z","repository":{"id":53101253,"uuid":"333263241","full_name":"polyforest/jsdoc-tsimport-plugin","owner":"polyforest","description":"A JSDoc plugin to support the typescript module import syntax.","archived":false,"fork":false,"pushed_at":"2023-04-25T04:59:40.000Z","size":77,"stargazers_count":34,"open_issues_count":11,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-01T10:04:02.589Z","etag":null,"topics":["import","jsdoc","module","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polyforest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-01-27T01:07:28.000Z","updated_at":"2024-11-17T13:14:37.000Z","dependencies_parsed_at":"2022-09-16T22:41:35.731Z","dependency_job_id":"855d225b-0f53-4efa-b01c-942626e9c533","html_url":"https://github.com/polyforest/jsdoc-tsimport-plugin","commit_stats":{"total_commits":25,"total_committers":3,"mean_commits":8.333333333333334,"dds":"0.16000000000000003","last_synced_commit":"129a3e28ad261a24249e090b9f414ebb10d79282"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyforest%2Fjsdoc-tsimport-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyforest%2Fjsdoc-tsimport-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyforest%2Fjsdoc-tsimport-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polyforest%2Fjsdoc-tsimport-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polyforest","download_url":"https://codeload.github.com/polyforest/jsdoc-tsimport-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119341,"owners_count":21050753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["import","jsdoc","module","typescript"],"created_at":"2024-12-07T12:07:03.076Z","updated_at":"2025-04-09T21:43:34.250Z","avatar_url":"https://github.com/polyforest.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jsdoc-tsimport-plugin\nA JSDoc plugin to support the Typescript import syntax.\n\n[![NPM Package](https://img.shields.io/npm/v/jsdoc-tsimport-plugin)](https://www.npmjs.com/package/jsdoc-tsimport-plugin)\n[![NPM Downloads](https://img.shields.io/npm/dw/jsdoc-tsimport-plugin)](https://www.npmtrends.com/jsdoc-tsimport-plugin)\n\n### What is it?\n\nA workaround to VSCode and WebStorm not supporting JSDoc typedef imports.\n\nWhat JSDocs expects:\n\n```js\n/**\n * @type {module:path/to/module~MyTypeDefName}\n */\n```\n\nWhat VSCode expects (as well as Webstorm to a limited degree):\n\n```js\n/**\n * @type {typeof import(\"./path/to/module\").MyTypeDefName}\n */\n```\n\nThis plugin adds hooks to JSDoc that translates the VSCode supported syntax into the JSDoc supported syntax.\n\n### Why?\n\nThis allows you to create typedef doclets in a file that can be shared. Just use the typescript-style imports within your doc comments, and then the plugin will translate when you build your jsdocs. This is preferable to adding unused es6/commonjs imports to your code, which may cause unintended side-effects, or fail linting requirements.\n\n### How?\n\nTo get started, first install this package with:\n```npm install --save-dev jsdoc-tsimport-plugin```\n\nThen in your `jsdoc.conf.json` settings, add the plugin:\n\n```\n\"plugins\": [\n  \"node_modules/jsdoc-tsimport-plugin/index.js\"\n]\n```\n\nThen, write your doc comment typedef import statements in the typescript style.\n\n```js\n/// src/model.js\n\n/** @file Model type definitions */\n/** @module */\n\n/**\n * An address model.\n *\n * @typedef {object} Address\n *\n * @property {number} houseNumber The house number.\n * @property {string} street The street.\n * @property {string} city The city.\n * @property {string} state The state.\n * @property {number} zip The zip.\n */\n```\n\n```js\n/// src/addressView.js\n\n/** @typedef {import('./model.js').Address} Address\n```\n\nIf everything is working, when you run `jsdoc` you should get a linkable definition for your type.\nExample:\n\n| Name  | Type | Description |\n| ------------- | ------------- | -------------- |\n| shippingAddress  | [module:model~Address](#)  | The shipping address. |\n\n#### ESLint\n\nIf you're using ESLint, we recommend turning the built-in jsdoc validation off (it's deprecated anyway), and using [eslint-plugin-jsdoc](https://www.npmjs.com/package/eslint-plugin-jsdoc).\nAnd then set your jsdoc style to 'typescript'.\n\n`.eslintrc.json`\n```json\n{\n  \"extends\": [\n    \"plugin:jsdoc/recommended\"\n  ],\n  \"plugins\": [\"jsdoc\"],\n  \"rules\": {\n    \"valid-jsdoc\": \"off\"\n  },\n  \"settings\": {\n    \"jsdoc\": {\n      \"mode\": \"typescript\"\n    }\n  }\n}\n```\n\n### Considerations\n\nThis will take into account `@module` tags, multiple source directories, and complex paths.\n\nFor example:\n\n```js\n/// src/path/a/model.js\n\n/** @module call/me/ishmael */\n\n/**\n * Another type definition.\n *\n * @typedef {object} MyType\n * @property {number} foo\n */\n```\n\n```js\n/// src/path/b/view.js\n\n/**\n * @param {import('../a/model').MyType} data\n */\nfunction show(data) {}\n```\n\nIn that example the `import('../a/model').MyType` will be replaced in jsdoc with `module:call/me/ishmael~MyType`.\n\n### Known Limitations\n\nIn Webstorm, the Typescript import syntax is only partially supported. It will not type hint for local files this way. However, the JSDoc module syntax is entirely unsupported and shows error markers, so this is still an improvement.\n\n### References\n\nThis references the issues:\n- https://github.com/jsdoc/jsdoc/issues/1537\n- https://github.com/jsdoc/jsdoc/issues/1645\n- https://github.com/jsdoc/jsdoc/issues/1632\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolyforest%2Fjsdoc-tsimport-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolyforest%2Fjsdoc-tsimport-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolyforest%2Fjsdoc-tsimport-plugin/lists"}