remark
Remark config type safety #1341
Replies: 1 comment 6 replies
-
|
Hey @jaydenseric! 👋 |
Beta Was this translation helpful? Give feedback.
-
|
Hi! It's not clear reading those preset docs what my
As a general rule, anything you import in your code is a direct dependency, and must be declared in your package with a version range. It's an established enough best practice that there are lint rules in the ecosystem to enforce this, e.g: It's should be self-evident the reasons why you need to declare your program's dependencies; I could explain some but that's kind of beyond the scope of what I have time for in this question/discussion. Transient dependencies are not part of the semver contract packages have; they are free to drop them or update major versions etc. at will as an implementation detail in minor or patch releases, as long as the package's declared public API isn't affected. If you are relying by pure coincidence on a transient dependency being installed at a particular version, via some other dependency, then it's very fragile and your code could break a lot over time. It also makes it hard to tell as a human what a projects dependencies are when reading the package file if some are undeclared.
Can you please show how to do that in my example config code? Via a triple slash reference comment at the top? |
Beta Was this translation helpful? Give feedback.
-
Right, I get the why, and agree on the front of lint and validate as much as possible.
Using a reference directive https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html#-reference-path- for example remark/packages/remark/index.d.ts Lines 1 to 2 in 8ca9469
Using the repo and the type linked in my last comment, to make that more concrete. /**
* @satisfies {import("unified-engine").Preset} |
Beta Was this translation helpful? Give feedback.
-
There might be some confusion; ESLint isn't to do with the question raised in this discussion. I only referenced a community ESLint rule that enforces no imports from transient dependencies as evidence that it's a best practice. Right now, the code examples for installing and configuring Remark via JavaScript don't show:
Because it's such an awkward thing, to reference and import from dependencies of dependencies in your config module, I think the API design could do with an overhaul. I would like to be able to import types from just the dev dependencies I install, to be able to configure those dev dependencies with type safety. I have tried your suggestions, and ran into TS errors with this // @ts-check
/// <reference types="remark-parse" />
/// <reference types="remark-stringify" />
import remarkLintHeadingIncrement from "remark-lint-heading-increment";
/**
* Remark configuration.
* @satisfies {import("unified-engine").Preset}
*/
const remarkConfig = {
plugins: ["remark-lint", remarkLintHeadingIncrement],
};
export default remarkConfig;The If you replace |
Beta Was this translation helpful? Give feedback.
-
raising a question about something, implies that the answer is unknown; so if you don’t ask about eslint, it might very well be that the answer is about eslint.
Which examples do you mean?
Whether to include typescript dependencies in
The difference is not type safety.
Sometimes, the disappearance of a particular error, does not mean an improvement. Type checking plugins and options is quite complex. The Still, coming back to your root problem, of how to type your config file, I would go with: /**
* @import {PluginTuple, Preset} from 'unified'
*/
import remarkLint from 'remark-lint'
import remarkLintHeadingIncrement from 'remark-lint-heading-increment'
import remarkLintCheckboxCharacterStyle from 'remark-lint-checkbox-character-style'
import remarkLintCodeBlockStyle from 'remark-lint-code-block-style'
/**
* My remark preset.
*
* @satisfies {Preset}
*/
const remarkPresetJayden = {
plugins: [
remarkLint,
remarkLintHeadingIncrement,
/** @type {PluginTuple<[import('remark-lint-checkbox-character-style').Options]>} */
([remarkLintCheckboxCharacterStyle, 'consistent']),
/** @type {PluginTuple<[import('remark-lint-code-block-style').Options]>} */
([remarkLintCodeBlockStyle, 'asdasdasd'])
]
}
export default remarkPresetJaydenThis shows two plugins with options: the first correct, the second incorrect. The first is typed okay, the other has a type error. Showing “type safety”. Furthermore, this uses a regular unified preset, where you load packages yourself. That means you can use this generally in JavaScript, everywhere you want. Finally, for this, make sure to install, as dependencies, |
Beta Was this translation helpful? Give feedback.
-
Adding on. I assume the documentation being referenced here is a readme. I'm cautious adding more information about best practices of external tooling because:
It feels like the ask is for remarkjs to essentially enforce your eslint config.
It may be possible, there are some partial solutions linked in unifiedjs/unified#221 |
Beta Was this translation helpful? Give feedback.
-
How are you supposed to type Remark config with TypeScript flavor JSDoc comments?
For example, in
.remarkrc.mjs:In that code example, what should the
?placeholders be?considering the only direct dev dependencies I have added to the project is
remark-lintandremark-lint-heading-increment, an ideal solution would:settingsonly available settings should be typed.Beta Was this translation helpful? Give feedback.
All reactions