This package contains a bunch of tools and default configurations to help build libraries and sharable packages. Refer to the API Docs below for the types, variables, and functions that are exposed.
- Binaries
-
API Docs
- Type Aliases
- Variables
-
Functions
appendFileExtensionForEsm()- appendFileExtensionForImports()
- configureWithPossibleExtension()
- createCombinedPackageJsonDependencies()
- cssModification()
- generateEslintConfigs()
- generatePrettierConfigs()
- generateViteConfigs()
- generateViteMultiFileLibConfigs()
- getCjsConfigs()
- getHtmlConfigs()
- getJsConfigs()
- getJsonConfigs()
- getTsConfigs()
- getVueConfigs()
- keepOnlyExistentPaths()
- lintAndReformat()
- modifySourceContentsChain()
- replaceAliasWithTsconfigPaths()
- runEslint()
- runPrettier()
- spawnCommand()
- updatePackageJsonVersions()
The following binaries are exposed:
Usage:
{run-eslint|run-prettier|run-linter} [flags...]
Flags:
-c, --command <string> Optional list of commands to run after linting is complete
-d, --dir <string> Directory to scan
-e, --extension <string> Extension to scan. Ex: .ts
-f, --file <string> File to include. Ex: ./my-file.ts
-h, --help Show help
-g, --include-general-files Include some of the general files like package.json, prettier.config.cjs, etc when linting
-k, --kill-on-error Kill the process when a linter fails rather than continuing on initial run
-w, --watch Enable watch mode
-s, --watch-only Skip the initial linting and only watch files
There are 3 binaries available here: run-eslint
, run-prettier
, and run-linter
. The first two simply runs the
linting tool in their name while the latter runs both of them sequentially (first ESLint, then Prettier).
Note that in order for this to work, you will also need to have the following packages included:
- eslint
- prettier
Usage:
run-typedoc [flags...]
Flags:
-b, --base-readme <string> The base file to inject the generated content into. (default: "./base-readme.md")
-h, --help Show help
-v, --include-vue-doc-gen Include the generation of vue-docgen-cli.
-i, --input-file <string> The input file. (default: "./src/index.ts")
-o, --out-dir <string> Directory to output the generated content. (default: "./docs")
-c, --vue-doc-gen-config-file <string> The path to the configuration file for vue-docgen-cli. (default: "./docgen.config.cjs")
So what the whole point of this binary? It basically came into existent because I couldn't find a single tool that generates good-looking API Docs and good documentation for Vue components. As such, this actually combines 2 tools, TypeDoc and Vue-DocGen.
The way this works is that it will find a base file and then inject into it contents from the two tools by replacing
some of the placeholder text in it. As such, you'll be able to include custom content within the doc (the documentation
you are reading about these binaries are custom as an example). Below are the text it will look for and replace (note
that both of the options requires the string to be wrapped around with ---
, the only reason I'm not including it below
is that I used some very simply string matching and replace and as such will probably replace the string too if I have
it exactly as is):
-
Insert API Docs
: Will be replaced with the contents of TypeDoc. -
Insert components
: Will be replaced with the contents of Vue-DocGen.
Note that in order for this to work, you will also need to have the following packages included:
- typedoc
- typedoc-plugin-markdown
Usage:
create-combined-package-json-dependencies [flags...]
Flags:
-d, --dry-run Enable dry-run mode which not actually write the target file. If changing to "false" must be passed as "-d=false". (default: true)
-h, --help Show help
-s, --source-path <string> Either the path or glob pattern for the package.json files to read to get the dependencies.
-t, --target-path <string> Path to target package.json that will be created.
-n, --write-on-no-conflict-only Enable to only write the target files if there are no conflict between sources. (default: true)
Usage:
update-package-json-versions [flags...]
Flags:
-d, --dry-run Enable dry-run mode which will not actually update the target package.json. If changing to "false" must be passed as "-d=false". (default: true)
-h, --help Show help
-s, --source-path <string> Path to source package.json with versions to copy from.
-t, --target-path <string> Path to target package.json that will have its versions updated.
These 2 binaries together can help you keep versions of various dependencies in-sync across multiple packages even if
they are not in the same repository. Most other tooling only support something similar to this if all the packages are
part of the same repository so this package came into existent to solve those other cases. This is a good way to ensure
you use the same version of dependencies that other dependencies you use rely on. For example, this package, since it
provides a pattern for building libraries and makes many assumptions, relies on the fact that certain dependencies are
at certain versions. Should you choose to follow the patterns of this package and want to keep your versions of
dependencies in-sync with this package and other packages under its same mono-repositories, you can do so. Just
basically run update-package-json-versions
by using the exported package-versions.json
from this package as a source
and set to target to your package.json
and you will end up using the same exact versions. Note that you can also just
specify the path directly to this package's package.json
file to only care about the dependencies of this package, the
other file I've mentioned is a combined view of all the packages under the same mono repository. Should you want to
create the same combined file, you can use create-combined-package-json-dependencies
binary to achieve that.
Note that if you a providing a glob for the pattern, be sure to wrap it in quotes.
EslintConfigType:
"cjs"
|"html"
|"js"
|"json"
|"ts"
|"vue"
eslint.ts:17
EslintConfigsParams: {
baseDir
:string
;configureCjs
: (configs
) =>Linter.ConfigOverride
;configureHtml
: (configs
) =>Linter.ConfigOverride
;configureJs
: (configs
) =>Linter.ConfigOverride
;configureJson
: (configs
) =>Linter.ConfigOverride
;configureTs
: (configs
) =>Linter.ConfigOverride
;configureVue
: (configs
) =>Linter.ConfigOverride
;enable
:EslintConfigType
[]; }
Name | Type | Description |
---|---|---|
baseDir |
string |
The base directory for your package. |
configureCjs |
(configs ) => Linter.ConfigOverride
|
If we need to override or extend the configurations for .cjs files, this handler can be provided. |
configureHtml |
(configs ) => Linter.ConfigOverride
|
If we need to override or extend the configurations for .html files, this handler can be provided. |
configureJs |
(configs ) => Linter.ConfigOverride
|
If we need to override or extend the configurations for .js files, this handler can be provided. |
configureJson |
(configs ) => Linter.ConfigOverride
|
If we need to override or extend the configurations for .json files, this handler can be provided. |
configureTs |
(configs ) => Linter.ConfigOverride
|
If we need to override or extend the configurations for .ts files, this handler can be provided. |
configureVue |
(configs ) => Linter.ConfigOverride
|
If we need to override or extend the configurations for .vue files, this handler can be provided. |
enable |
EslintConfigType [] |
List of files to enable linting support for. |
eslint.ts:19
ModifySourceContentsChainArgs:
ModifySourceContentsChainHandlerCreatorBuildArgs
& {handlerCreators
:ModifySourceContentsChainHandlerCreator
[]; }
Arguments for the function modifySourceContentsChain.
Name | Type | Description |
---|---|---|
handlerCreators |
ModifySourceContentsChainHandlerCreator [] |
List of creators for handlers. |
esbuild-plugins/modify-source-contents-chain.ts:41
ModifySourceContentsChainHandler: (
args
) => {contents
:string
; }
Handler to be given the path of the file whose content is also given. It should return an object with the updated contents before it is passed to the next handler.
Parameter | Type |
---|---|
args |
object |
args.contents |
string |
args.path |
string |
{contents
: string
; }
Name | Type |
---|---|
contents |
string |
esbuild-plugins/modify-source-contents-chain.ts:29
ModifySourceContentsChainHandlerCreator: (
args
) =>ModifySourceContentsChainHandler
Use to create the handler as part of the build step.
Parameter | Type |
---|---|
args |
ModifySourceContentsChainHandlerCreatorBuildArgs & {build : PluginBuild ; } |
ModifySourceContentsChainHandler
esbuild-plugins/modify-source-contents-chain.ts:34
ModifySourceContentsChainHandlerCreatorBuildArgs: {
cwd
:string
;debug
:boolean
;extensions
:string
[]; }
Arguments passed to the ModifySourceContentsChainHandlerCreator during the build step.
Name | Type | Description |
---|---|---|
cwd |
string |
The current working directory. Defaults to whatever value is returned by process.cwd() . |
debug |
boolean |
Set to true to output some debugging information while executing. Defaults to false . |
extensions |
string [] |
The list of file extensions to parse. Defaults to [".ts"] . |
esbuild-plugins/modify-source-contents-chain.ts:8
RunEsLintPrettierParams: {
dirs
:string
[];extensions
:string
[];files
:string
[]; }
Name | Type | Description |
---|---|---|
dirs |
string [] |
List of directory glob patterns to run the linter on. |
extensions |
string [] |
List of file extensions to run the linter on. |
files |
string [] |
List of files to run the linter on. |
misc.ts:5
const
BASE_JAVASCRIPT_RULES:Partial
<Linter.RulesRecord
>
Shared rules for .cjs
and .js
files.
eslint/javascript-configs.ts:6
const
GENERAL_FILES:string
[]
General list of files that most packages should have that we want to lint and format.
misc.ts:25
appendFileExtensionForEsm(
args
):ModifySourceContentsChainHandler
This will append the file extension to the end of relative imports if we are building for ESM.
Parameter | Type |
---|---|
args |
ModifySourceContentsChainHandlerCreatorBuildArgs & {build : PluginBuild ; } |
ModifySourceContentsChainHandler
Just use appendFileExtensionForImports
which will add it for both ESM and CJS since they'll end up
needing it.
esbuild-plugins/handler-creators/append-file-extension-for-esm.ts:10
appendFileExtensionForImports(
args
):ModifySourceContentsChainHandler
This will append the file extension to the end of relative imports if we are building for ESM and CJS.
Parameter | Type |
---|---|
args |
ModifySourceContentsChainHandlerCreatorBuildArgs & {build : PluginBuild ; } |
ModifySourceContentsChainHandler
esbuild-plugins/handler-creators/append-file-extension-for-imports.ts:28
configureWithPossibleExtension(
baseConfigs
,extender
):Linter.ConfigOverride
Given the base configurations, if an extender function is provided, execute it to retrieve the extended configurations.
Parameter | Type |
---|---|
baseConfigs |
ConfigOverride <RulesRecord > |
extender |
(configs ) => ConfigOverride <RulesRecord > |
Linter.ConfigOverride
eslint.ts:65
createCombinedPackageJsonDependencies():
void
Combine all the versions of the various given package.json files into one. Note that this will create a package.json file that will simply write all dependencies into the "dependencies" block on the package.json.
void
package-json-utils.ts:64
cssModification():
Plugin
This plugin basically removes duplicate charset tags in the final CSS file as well as remove those legacy IE hacks.
Plugin
postcss-plugins/css-modification.ts:6
generateEslintConfigs(
configs
):Linter.Config
Generate the configurations to use for ESLint.
Note the following unique features while the configurations are generated:
- Configurations for *.ts files will inherit the plugins and rules set by the *.js configurations.
- Configurations for *.vue files will inherit the plugins, and rules set by the *.ts configurations.
Parameter | Type |
---|---|
configs |
EslintConfigsParams |
Linter.Config
eslint.ts:79
generatePrettierConfigs():
Config
Get the default configurations for Prettier.
Config
prettier.ts:9
generateViteConfigs():
Promise
<UserConfig
>
Get the default configurations for Vite.
Promise
<UserConfig
>
vite.ts:8
generateViteMultiFileLibConfigs(
entries
):Promise
<UserConfig
>
Get the default configurations for Vite if we want to generate individual files as part of a library export. This
will make it so that all the files referenced by the given entries
will be generated using the same directory
structure as it is in the src
folder. For Vue components, it will remove the .vue
in the file extension. For the
extracted CSS from the Vue files, it will also place them in the same folder as the component itself.
Parameter | Type |
---|---|
entries |
string [] |
Promise
<UserConfig
>
vite.ts:24
getCjsConfigs():
Linter.ConfigOverride
Get the default configurations for .cjs
files.
Linter.ConfigOverride
eslint/javascript-configs.ts:14
getHtmlConfigs():
Linter.ConfigOverride
Get the default configurations for .html
files.
Linter.ConfigOverride
eslint/html-configs.ts:6
getJsConfigs():
Linter.ConfigOverride
Get the default configurations for .js
files.
Linter.ConfigOverride
eslint/javascript-configs.ts:33
getJsonConfigs():
Linter.ConfigOverride
Get the default configurations for .json
files.
Linter.ConfigOverride
eslint/json-configs.ts:6
getTsConfigs(
jsConfigs
,baseDir
):Linter.ConfigOverride
Get the default configurations for .ts
files.
Parameter | Type |
---|---|
jsConfigs |
ConfigOverride <RulesRecord > |
baseDir |
string |
Linter.ConfigOverride
eslint/typescript-configs.ts:7
getVueConfigs(
tsConfigs
):Linter.ConfigOverride
Get default configurations for .vue
files.
Parameter | Type |
---|---|
tsConfigs |
ConfigOverride <RulesRecord > |
Linter.ConfigOverride
eslint/vue-configs.ts:6
keepOnlyExistentPaths(
paths
):string
[]
Given a list of paths, remove files that doesn't exists.
Parameter | Type |
---|---|
paths |
string [] |
string
[]
misc.ts:37
lintAndReformat(
dirs
,extensions
,files
,options
):Plugin
Lint and reformat the code.
Note that this contains an escape hatch to linting so you can still "build" by including the environment variable
DISABLE_LINTING
.
Parameter | Type | Default value |
---|---|---|
dirs |
string [] |
undefined |
extensions |
string [] |
undefined |
files |
string [] |
GENERAL_FILES |
options |
object |
{} |
options.verifyTs ? |
boolean |
undefined |
options.verifyVueTs ? |
boolean |
undefined |
Plugin
vite-plugins/lint-and-reformat.ts:69
modifySourceContentsChain(
__namedParameters
):Plugin
While esbuild allows you to add multiple handlers for its onLoad event, once one of the handler returns something, the subsequent handlers will not run. That means we can't have multiple handlers that updates the source content. This plugin allows for the possibility.
Parameter | Type |
---|---|
__namedParameters |
ModifySourceContentsChainArgs |
Plugin
esbuild-plugins/modify-source-contents-chain.ts:64
replaceAliasWithTsconfigPaths(
args
):ModifySourceContentsChainHandler
This plugin allows the use of path aliases in TSConfig, and it will be replaced with the mapped value in the generated output. This plugin makes use of simple string matching and replace so that it can still be fast. If you want to use a plugin that is likely safer which actually parses the code and does the replacement, you can look at the plugin available here: https://github.com/wjfei/esbuild-plugin-tsconfig-paths
Parameter | Type |
---|---|
args |
ModifySourceContentsChainHandlerCreatorBuildArgs & {build : PluginBuild ; } |
ModifySourceContentsChainHandler
Throws a tsconfig-path#ConfigLoaderFailResult
If we cannot load the tsconfig.json
file for this package.
esbuild-plugins/handler-creators/replace-alias-with-tsconfig-paths.ts:24
runEslint(
params
):SpawnSyncReturns
<Buffer
>
Execute the command to run ESLint.
Parameter | Type |
---|---|
params |
RunEsLintPrettierParams |
SpawnSyncReturns
<Buffer
>
eslint.ts:104
runPrettier(
params
):SpawnSyncReturns
<Buffer
>
Execute the command to run Prettier.
Parameter | Type |
---|---|
params |
RunEsLintPrettierParams |
SpawnSyncReturns
<Buffer
>
prettier.ts:27
spawnCommand(
command
):SpawnSyncReturns
<Buffer
>
Spawn the given command synchronously and passing along the current environment variables.
Parameter | Type |
---|---|
command |
string |
SpawnSyncReturns
<Buffer
>
spawn.ts:6
updatePackageJsonVersions():
void
Retrieve all the versions from the source package.json and update the target package.json with the versions from the source.
void
package-json-utils.ts:176