json.macro
Load any json file at build time using babel-plugin-macros.
Table of Contents
Usage
json.macro
is designed to be used with babel-plugin-macros to inline all your json file imports.
Setup
First, install the plugin and it's peer dependency (babel-plugin-macros
). Since the macro is compiled away during the build, it should be installed as a development dependency.
npm install --save-dev json.macro babel-plugin-macros
or
yarn add -D json.macro babel-plugin-macros
Once installed make sure to add the 'babel-plugin-macros' to your babel.config.js
(or .babelrc
) file.
.babelrc
{ "plugins": [ "other-plugins",+ "macros", ]}
babel.config.js
module.exports = { // rest of config..., plugins: [ ...otherPlugins,+ 'macros', ]}
Code Example
For the following json file: ./my-json.json
this code will load a json file from the provided path. The path can be relative to the file it's being used from or an absolute path. If the file can't be resolved the build will fail.
/path/to/my-json.json
This will load it
/path/to/my-js.js
; const myJson = ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const myJson = custom: 1 ;
Like magic :-)
API
Function | Description |
---|---|
getVersion(verbose) |
Get the semver compatible version from the package.json file. |
loadJson(filePath, path) |
This loads a json file from the provided path. The path can be relative to the file it's being used from, an absolute path, or a path to your node_modules folder.If the file can't be resolved the build will fail. |
loadJsonFiles(pattern, ...patterns) |
Load all the json files matching the provided glob patterns. |
loadPackageJson() |
Load the nearest parent package.json file. |
loadTsConfigJson() |
Load the nearest parent tsconfig.json file. |
writeJson(json, filePath) |
Write a json object to a relative file path. |
getVersion()
Get the semver compatible version from the package.json file.
;;
Parameters
Parameter | Type | Description |
---|---|---|
verbose | boolean |
When true will return an object representing the semantic version |
Description
This will throw a build error if the semver version in your package.json is not valid.
Example
; const versionString = ;const versionStringAlt = ;const versionObject = ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const versionString = '1.19.2';const versionStringAlt = '1.19.2';const versionObject = major: 1 minor: 19 patch: 2 version: '1.19.2' ;
loadJson()
This loads a json file from the provided path. The path can be relative to the file it's being used from, an absolute path, or a path to your node_modules
folder.
If the file can't be resolved the build will fail.
;
Parameters
Parameter | Type | Description |
---|---|---|
filePath | string |
the relative file path to reference |
path | string |
the object path for the part of the object you want to load |
Description
For the following json file: ./my-json.json
This is how to load it at build time.
Examples
; const myJson = ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const myJson = custom: 1 ;
Magic :-)
To load from node_modules you can do something like the following.
; const jsonFromNode = ;
The above will be replaced with the full package.json file from the json.macro node_modules package.
If you are using typescript you can specify the expected return type by annotating the variable created.
; ;
If a second parameter is passed, this can also load a specific key path from a json file.
./my-json.json
; const value = ;const value2 = ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const value = 1;const value2 = true;
loadJsonFiles()
Load all the json files matching the provided patterns.
;
Parameters
Parameter | Type | Description |
---|---|---|
pattern |
string |
This function requires at least one json file pattern |
...patterns |
string[] |
Multiple patterns can be added |
Description
If no files match then an empty array is returned.
Examples
; const jsonArray = ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const jsonArray = custom: 1 another: 2 ;
If you are using typescript you can specify the expected return type by annotating the variable created.
; ;
loadPackageJson()
Load the nearest parent package.json
file.
;;
Parameters
Parameter | Type | Description |
---|---|---|
key | keyof PackageJson |
The property you want to load from the package.json file |
Description
You can also provide a key property which will load the property corresponding to the key from the nearest package.json
.
Examples
; const packageJson = ;const name = ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const packageJson = name: 'my-package' version: '1.0.0' private: true ;const name = '1.0.0';
For typescript users, the types are automatically inferred using the PackageJson
type from the [type-fest
](https://github.com/sindresorhus/type-fest) library.
loadTsConfigJson()
Load the nearest parent tsconfig.json
file.
;
Remarks
You can customise the name of the file searched for.
Example
; const tsconfig = ;const customTsConfig = ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const tsconfig = compilerOptions: {} ;const customTsConfig = compilerOptions: paths: ;
For typescript users, the types are automatically inferred using the TsConfigJson
type from the [type-fest
](https://github.com/sindresorhus/type-fest) library.
writeJson()
Write a JSON object to a relative file path.
;
Parameters
Parameter | Type | Description |
---|---|---|
json | any |
The json object to be written |
filePath | string |
Where the json object will be written to. |
Returns:
Type
Remarks
Sometimes it's easier to create an object that needs to follow certain type rules in typescript and then export it to a JSON object. How to do this though?
This method wraps the JSON object you create (statically and not dynamically) and will output to the provided filePath
at build time.
Examples
; ;
Compiles to ↓ ↓ ↓ ↓ ↓ ↓
const json = config: true type: 'array' ;
And ./config.json
is written as.
One thing to be aware of is that this method only supports inline or statically inferable values. You can't use any dynamic values, like return values from a function call.
; ;; writeJson, './file.json'; // Static ✅writeJsoncustom, './file.json'; // Static ✅ writeJsoncreateJson, './file.json'; // Dynamic ❌
json.macro/types
You might find yourself wanting to use the PackageJson
or TsConfigJson
types in your own code. For this reason this file re-exports them from type-fest
to save you the hassle of adding another direct dependency.
; ;;
There is also a SemanticVersion
interface which exported by the same file. This is the return type for the getVersion(true)
function call.
; ;
Contributing
Dive into the codebase with Gitpod.
Versioning
This project uses SemVer for versioning. For the versions available, see the tags on this repository.
License
This project is licensed under the MIT License - see the LICENSE file for details
Contributors
Ifiok Jr. 💻 |