What is an Invariant and How is It Different From Assert?
The two are not all that different in that they server similar purposes, there are however several differences when it comes to how they are used in Next.js.
Error Handling
The use of an invariant is typically to throw an error that was intended to be caught and handled by, say, a serverless function. An assert on the other hand will typically terminate the program upon a failure of said assert.
Performance
In general the expectation is that invariants are something used as part of development to improve the speed of your coding by providing you more valuable feedback. As such, they are typically removed before a production build. There is a way however, we can keep them in our code as I’ll explain later.
Assertions, if remained in your code, can negatively affect performance.
Message Formatting
Due to their usage, assertions are typically very straight-forward in their messaging while invariants, which are integrated into the Next.js framework, can have a much more sophisticated response and may have special handing and formatting in error displays. Let me provide some examples of what I mean.
import { invariant } from 'next/dist/server/future/route-modules/app-route/module';
function validateUserData(userData) {
const { id, name, email, age, roles } = userData;
invariant(
typeof id === 'string' && id.length === 36,
Invalid user ID: expected a 36-character string UUID, but got <span class="hljs-subst">${<span class="hljs-keyword">typeof</span> id === <span class="hljs-string">'string'</span> ? <span class="hljs-string">a ${id.length}-character string</span> : <span class="hljs-string">a ${typeof id}</span>}</span>. Please ensure you're passing a valid UUID.
);
invariant(
typeof name === 'string' && name.length >= 2 && name.length <= 50,
<span class="hljs-attr">Invalid</span> <span class="hljs-attr">name:</span> "</span><span class="hljs-subst"><span class="hljs-tag">${<span class="hljs-attr">name</span>}</span></span><span class="hljs-tag">"<span class="hljs-attr">.</span> <span class="hljs-attr">Name</span> <span class="hljs-attr">must</span> <span class="hljs-attr">be</span> <span class="hljs-attr">a</span> <span class="hljs-attr">string</span> <span class="hljs-attr">between</span> <span class="hljs-attr">2</span> <span class="hljs-attr">and</span> <span class="hljs-attr">50</span> <span class="hljs-attr">characters</span> <span class="hljs-attr">long.</span> <span class="hljs-attr">Current</span> <span class="hljs-attr">length:</span> </span><span class="hljs-subst"><span class="hljs-tag">${<span class="hljs-attr">name.length</span>}</span></span><span class="hljs-tag">
);
invariant(
typeof email === 'string' && /^[^<span class="hljs-attr">s@]+@[^<span class="hljs-attr">s@]+<span class="hljs-attr">.[^<span class="hljs-attr">s@]+$/.test(email),
<span class="hljs-attr">Invalid</span> <span class="hljs-attr">email</span> <span class="hljs-attr">address:</span> "</span><span class="hljs-subst"><span class="hljs-tag">${<span class="hljs-attr">email</span>}</span></span><span class="hljs-tag">"<span class="hljs-attr">.</span> <span class="hljs-attr">Please</span> <span class="hljs-attr">provide</span> <span class="hljs-attr">a</span> <span class="hljs-attr">valid</span> <span class="hljs-attr">email</span> <span class="hljs-attr">address</span> <span class="hljs-attr">in</span> <span class="hljs-attr">the</span> <span class="hljs-attr">format</span> <span class="hljs-attr">user</span>@<span class="hljs-attr">example.com</span>
);
invariant(
typeof age === 'number' && age >= 18 && age <= 120,
<span class="hljs-attr">Invalid</span> <span class="hljs-attr">age:</span> </span><span class="hljs-subst"><span class="hljs-tag">${<span class="hljs-attr">age</span>}</span></span><span class="hljs-tag"><span class="hljs-attr">.</span> <span class="hljs-attr">Age</span> <span class="hljs-attr">must</span> <span class="hljs-attr">be</span> <span class="hljs-attr">a</span> <span class="hljs-attr">number</span> <span class="hljs-attr">between</span> <span class="hljs-attr">18</span> <span class="hljs-attr">and</span> <span class="hljs-attr">120.</span> <span class="hljs-attr">If</span> <span class="hljs-attr">you</span>'<span class="hljs-attr">re</span> <span class="hljs-attr">trying</span> <span class="hljs-attr">to</span> <span class="hljs-attr">register</span> <span class="hljs-attr">a</span> <span class="hljs-attr">minor</span> <span class="hljs-attr">or</span> <span class="hljs-attr">someone</span> <span class="hljs-attr">over</span> <span class="hljs-attr">120</span>, <span class="hljs-attr">please</span> <span class="hljs-attr">contact</span> <span class="hljs-attr">support.</span>
);
invariant(
Array.isArray(roles) && roles.length > 0 && roles.every(role => typeof role === 'string'),
Invalid roles: <span class="hljs-subst">${<span class="hljs-built_in">JSON</span>.stringify(roles)}</span>. Roles must be a non-empty array of strings. Example of valid roles: ["user", "admin"]
);
console.log("User data is valid!");
}
// Example data to test invariants
try {
validateUserData({
id: '123', // Invalid ID
name: 'A', // Invalid name
email: 'invalid-email', // Invalid email
age: 15, // Invalid age
roles: ['user', 42] // Invalid roles
});
} catch (error) {
console.error("Validation Error:", error.message);
}
Now the above is perhaps far an away much more sophisticated than you might need, but it gives you a good example of what’s possible.
Usage Context
Invariants in Next.js are often used for checking configuration and API usage. I’ve become especially fond of using them in serverless functions. Assertions are more commonly used for logic and testing.
So when we think of the challenges we have of validating and testing within a serverless function, extracting the error message from that can often be a challenge. With invariants however, it’s a lot simpler. Have a look at the following example.
import { invariant } from 'next/dist/server/future/route-modules/app-route/module';
export default function handler(req, res) {
try {
// Some operation that might trigger an invariant
invariant(req.query.id, 'ID is required');
<span class="hljs-comment">// Rest of the handler logic...</span>
res.status(<span class="hljs-number">200</span>).json({ success: <span class="hljs-keyword">true</span> });
} catch (error) {
console.error('API Error:', error);
<span class="hljs-keyword">if</span> (process.env.NODE_ENV === <span class="hljs-string">'development'</span>) {
<span class="hljs-comment">// In development, send the full error message</span>
res.status(<span class="hljs-number">400</span>).json({ <span class="hljs-keyword">error</span>: <span class="hljs-keyword">error</span>.message });
} <span class="hljs-keyword">else</span> {
<span class="hljs-comment">// In production, send a generic message</span>
res.status(<span class="hljs-number">400</span>).json({ <span class="hljs-keyword">error</span>: 'An <span class="hljs-keyword">error</span> occurred. Please <span class="hljs-keyword">try</span> again.' });
}
}
}
Let’s walk through the above code for when the invariant throws an error “ID is required”.
- The invariant throws an error with the message "ID is required".
- This error is caught in the try/catch block.
-
In the catch block, we have this condition:
if (process.env.NODE_ENV === 'development') { // In development, send the full error message res.status(400).json({ error: error.message }); } -
Since we're in a development environment, this condition is true.
- The full error message ("ID is required") is sent back in the JSON response with a 400 status code.
So, if you were to make a request to this API endpoint in a development environment without providing an ID in the query parameters, you would receive a response like this:
{
"error": "ID is required"
}
This message would be visible in several places:
- In the Network tab of your browser's Developer Tools, you'd see this response body.
- If you're using a tool like Postman to test your API, you'd see this message in the response body.
- In your server logs or terminal where you're running your Next.js development server, you'd likely see a log of this error. Or if you have Docker Desktop running you’d see it in the rendering container.
- If you're calling this API from your frontend code and logging the error response, you'd see this message in your browser's console.
Keeping Invariants in Production Builds
If we want to keep invariants within production builds, we could build a simple library function to perform an environment check first, such as the following.
const isDev = process.env.NODE_ENV !== 'production';
export const customInvariant = (condition, message) => {
if (isDev) {
invariant(condition, message);
}
};
At least now, you can keep the invariant in place in your code in a manner that doesn’t interfere too much.
The most important thing to remember in all this is that by doing the necessary checks up front, we can improve the code that reaches our QA and Production environments and hopefully reduce the number of bugs reported back.
