What's a @type tag?

20th August 2021

I recently started a new Next.js project and noticed a difference in next.config.js compared to my other codebases.

/** @type {import('next').NextConfig} */
module.exports = {
  reactStrictMode: true,
};

The line /** @type {import('next').NextConfig} */ is new! So I wanted to take some time to understand what this is and why it was added.

Where did the change come from?

After digging through the Next.js codebase, I discovered a recent change to create-next-app, the tool I've used to bootstrap my projects. #27872 adds the new line for the Typescript template that I was using.

What is JSDoc?

This line is a JSDoc annotation. JSDoc is used to provide additional information about the Javascript code being written. It uses the special /** comment syntax while other types of comment are ignored.

The jsdoc CLI tool will read these comments and produce a website documenting your API. Many editors such as VSCode provide JSDoc support that enhances the IntelliSense capabilities.

Typescript & JSDoc

Typescript can be used to type-check JS files that use JSDoc annotations. It can be enabled on a per-file basis using the // @ts-check annotation.

// @ts-check

/** @type {import('next').NextConfig} */
module.exports = {
  reactStrictMode: true,
};

Alternatively, it can be enabled for all JS files using the checkJs setting in tsconfig.json.

{
  "compilerOptions": {
    "checkJs": true
  }
}

What is the @type tag?

@type {typeName} specifies the type that a value can contain or the return type of a function.

In the next.config.js example, the type expression import('next').NextConfig is an import type. It allows types to be imported from other files, however, it is only available in Typescript and not part of the JSDoc specification.