Skip to content

next lint vs next build

Posted on:May 20, 2025 at 05:02 AM

TypeScript Type Checking Discrepancy in Next.js: next lint vs next build

A common pitfall in TypeScript-based Next.js projects arises from a discrepancy between the next lint and next build commands. Where your code passes the linting stage but fails at build time due to un noticed type errors.

The Problem

Let’s consider this minimal example:

// copied from: https://github.com/vercel/next.js/discussions/31439
type TestComponentProps = {
  variable: 'someValue' | 'otherValue';
};

const TestComponent: React.FC<TestComponentProps> = ({ variable }) => {
  return <div>{variable}</div>;
};

const Home = () => {
  return <TestComponent variable="test" />;
};

export default Home;

Here, the TestComponent expects a prop variable of type 'someValue' | 'otherValue', but the Home component mistakenly passes the string "test" a value outside the expected union type.

What Happens?

Type error: Type '"test"' is not assignable to type '"someValue" | "otherValue"'.

Why didn’t next lint catch this?

Why This Happens

The reason lies in the differing goals of each command:

Use the TypeScript Compiler Separately

Run the TypeScript compiler in --noEmit mode to catch all type errors early:

tsc --noEmit

This ensures full type checking independently of the build process and if you a lot of these errors then its much more easier to deal it with tsc --noEmit otherwise you will have to run next build again and again till all the issues are fixed

For further discussion, check out the original GitHub thread.