next-dynamic-route-generator v3.0.0

Installation

npm i next-dynamic-route-generator

About

This is a tiny, simple package with built-in typescript support. This package is well tested and has custom error message for common user errors such as invalid argument passing, etc.

It is created as a helper to be used on next.js's getStaticPath and getStaticProps methods when we use next.js to create static sites where the site's contents(such as .md, .mdx, etc files) remain inside a directory of the same project and next.js builds the site according to the contents of that directory.

Overview

From here we are assuming that you are familiar with next.js. You need not be an expert though. You may read the next.js documentation if needed.

Some definitions:

paths: The same as paths of next.js. It is an array.

params: The params key of the parameter of getStaticProps.

route: The url string. Such as "about/about_me"

queryParam: Dynamic routes can be extended to catch all paths by adding three dots (...) inside the brackets such as pages/post/[...slug].js. See docs.
Here slug is the queryParam. That means for dynamic routes, the name of the file without the brackets and 3 dots(...) is the queryParam.

Let you have created a next.js project to generate a static blog. It has a posts directory, which contains the blog posts as .md files. The project file structure is something like this. (You may replace the .js to .ts if you want)

Now you want the URL of the site to be the same as posts directory structure. That is...

So you need to use getStaticPaths to generate those paths statically.

The returned object of the getStaticPaths must contain a key named as paths. This key is an array defining the route/URL structure of the site. Since you want the route/URL structure to be the same as the posts directory structure, you need to pass the paths key accordingly.
And here comes next-dynamic-route-generator to rescue you. It provides a method getPaths which will generate the paths key for you. This method is described here.

You will also need to work with getStaticProps method. The getStaticProps method takes a parameter which has a params key.

From the params key you can get the current route and then fetch the contents(.md/.mdx or other files). Here also we have got your back. If the params key is not undefined then you can get the route by generateRoute method. This method is described here.

Sometimes you may have some routes and you want to generate paths. This is possible using generatePaths method. This method is described here

The pages directory is a special directory in next.js. Inside the pages directory create a .js/.ts file named as [...slug].js/ts . Here the [] and ... have special meaning(see here). The file name can be anything other than [...slug] such as [...param], [...a] etc. If the filename is [...slug].js/ts then here queryParam is slug

importing

import getPaths, { generateRoute } from "next-dynamic-route-generator";

Now on the [...slug].js/ts file, getStaticPaths and getStaticProps are needed to be implemented.

getPaths takes an object as parameter. The keys are,

dirPath (type: string, required): the path of the directory from root where your posts or contents remain and the extension of the files you want to capture.
On the previous example, it is "../posts"

queryParam (type:string, required): The queryParam. For the previous example, it will be "slug".

extension (type:string, optional): The extension of the files we want to capture.
In the previous example, it is ".md".

globPattern (type:string, optional): The glob pattern to match the files we want to capture.
On the previous example, it will be "**/*.md".

Remind, extension and globPattern are optional individually. But you must pass at least one of them. If both are passed the files will be captured according to extension key.

So, For our previous example it will

const paths = getPaths({
    dirPath: "../posts",
    queryParam: "slug",
    extension: ".md"
});

If the params key exists on the parameter of getStaticProps and it is an array of strings, then the corresponding route can be generated using generateRoute method. The params key will always be an array of strings if the paths were generated using getPaths.
It will return the route as a string.

generateRoute also takes an object as parameter. The keys are,

params (required): params key of the object that is passed on getStaticProps.See here

queryParam (type:string, required): The queryParam.

dirPath (string, optional): If we want our route to contain the dirPath then we need to pass it.

extension (string, optional): To get the route with extension pass one.

absolute (boolean, optional): Pass true to get absolute route. default is false.

So, For our previous example it will be

export async function getStaticProps(context) {
    if (context.params) {
        const route = generateRoute({
            params: context.params,
            queryParam: "slug",
            dirPath: "post,
            extension: ".md",
            absolute: true
        });
    }
}

This will simple take an object with two keys, they are routes and queryParam. Both are required.
routes is an array of strings containing routes.
It will return paths of those routes.

Error handling

The getStaticPaths and getStaticProps methods are called only at the time of building the static site. They are not something like express.js middleware functions, which run for each API request. So, it is not suitable to catch the error and let it go. Rather the user/developer should be shown directly if anything wrong happens so that he can take measures and build the site perfectly. So, here we have validated the user input(method arguments) and thrown error with an error message so that the user can easily catch what has gone wrong.