magipoka v0.0.3
Magipoka
Magipoka is a library for outputting *.d.ts
files for type-safe routing from directory structures. It can be used to achieve zero-runtime type-safe routing.
Feature
You can use Magipoka to output *.d.ts
file to insert a type for type-safe routing into the Supported frameworks.
For example, It you output next/link
as the target, it will insert the Union type generated from the pages
directory into the <Link />
props that next/link
exports as default.
##### Next.js pages directory #####
.
├── pages
| ├── user
| | └── [uid].tsx
| ├── _app.tsx
| ├── hoge.tsx
| └── index.tsx
// magipoka.d.ts
declare module "next/link" {
// The types generated based on routing `pages` directory in Next.js
type PagesType = "/" | "/hoge" | `/user/${string}/`
type LinkProps = {
href: UrlObject | PagesType; // Insert the generated Union type
// ...
};
export default Link(props: LinkProps): JSX;
}
By including the above generated *.d.ts
file in your Next.js project, you can use type-safe routing where you using <Link />
.
import Link from "next/link";
const AnyComponent = () => {
return (
{/* 🛑 The following URL is an invalid URL and will cause a type error */}
<Link href="/bad/url">
<a>any link</a>
</Link>
);
};
About trailing slash
If the path contains uncertain values such as parameters, such as in dynamic routing in Next.js, /
is added to the end of the generated type. This is due to the limitations of TypeScript's template string types. If you don't like this behavior, you'll need to use a utility function to remove the trailing slash.
import Link from "next/link";
import { NextPagesType } from "magipoka/next";
const r = (path: NextPagesType): NextPagesType => {
if (path === "/") return path;
return path.replace(/\/$/, "") as NextPagesType;
};
const AnyComponent = () => {
return (
<>
{/* 🛑 Valid path, but error due to type restriction */}
<Link href="/user/1">
<a>any link</a>
</Link>
{/* ✅ Make it be treated as "/user/1" */}
<Link href={r("/user/1/")}>
<a>any link</a>
</Link>
{/* ✅ If the trailing slash is acceptable, you can leave it as it is. */}
<Link href="/user/1/">
<a>any link</a>
</Link>
</>
);
};
About Type Helpers
Template string types are not displayed as input completions on some editors such as VS Code. To avoid this, Magipoka adds a string starting with path: *
to the generated type.
For example:
// magipoka.d.ts
declare module "next/link" {
// The types generated based on routing `pages` directory in Next.js
type PagesType =
| "/"
| "/hoge"
| `/user/${string}/`
// After that, helper type
| "path:/"
| "path:/hoge"
| "path:/user/[uid]"; // For helper type, display the file name of the generator
// ...
}
However, although these helper types do not result in type errors, they can result in run-time errors.
If you don't like this behavior, you can disable it with the --no-type-helper
option or typeHelper
in magipoka.config.js.
$> magipoka --no-type-helper
or
module.exports = {
typeHelper: false,
};
Install
npm (Local install)
$> npm i --save-dev magipoka
yarn (Local install)
$> yarn add --dev magipoka
Usage
To output a *.d.ts
file, you can either set the options with generate
command and run it, or create a config file and run the default command
For the generate
command
In the generate
command, the target to be output is passed as arguments, and other settings are set using options.
$> magipoka generate [options] <targets...>
Now (2022/02), only next
and next/link
are available for output targets, but more will be added in the future.
You can set multiple output targets, but if a main target such as next
is specified, sub-targets such as next/link
will be ignored.( Because when next
is specified, next/link
is also set )
The options are as follows.
Options:
-f, --force Forces the output of the files
-r, --rootDir <path> set a root directory path
-o, --outDir <path> set a output directry path
-n, --filename <name> set a output filename
-c, --config <path> set a config path
-t, --type-helper set a flag for the Type Helper
--no-type-helper disable type helper
-h, --help display help for command
Even if there is a config file, if these options are specified on the command line, the value of the options will take precedence.
For default command
If you have a config file, you can use the default command to generate a *.d.ts
file.
$> magipoka
By defualt, it reads magipoka.config.js
in the root directory, but you can set a relative path to the config file by using the -c, --config
option.
$> magipoka --config ./path/to/magipoka.config.js
Config File
You can use magipoka.config.js
to config the output settings, and the values that can be set are as follows.
// magipoka.config.js
/** @type {import("magipoka").MagipokaConfig} */
module.exports = {
/**
* Allow files to be overwritten
*/
force: false,
/**
* Enable Type Helpers
*/
typeHelper: true,
/**
* Root directory path
*/
rootDir: "./",
/**
* Output directory path
*/
outDir: "./dist",
/**
* Output file name
*/
filename: "magipoka.d.ts",
/**
* Target of the type to generate
*/
target: [],
};