Switching to express.json(): A Practical Guide for Modern Express Apps

Why Replace body-parser?

Many Express 4.x projects still import the separate body-parser package to handle JSON payloads. Since Express v4.16.0 the express.json() middleware is built‑in, providing the same functionality without an extra dependency. Removing body-parser simplifies the dependency tree, reduces bundle size, and aligns with the official Express recommendation.

Getting Started with express.json()

To enable JSON parsing, add the middleware at the top of your router stack:

const express = require('express');
const app = express();

// Built‑in JSON parser – no external dependency
app.use(express.json());

app.post('/api/data', (req, res) => {
  // req.body now contains the parsed JSON object
  res.json({ received: req.body });
});

Express automatically checks the Content-Type header for application/json. If the header is missing or set to a different type, req.body will be undefined and the request will proceed to the next middleware.

Customizing Limits and Content Types

The default payload size is 100 KB. For larger APIs you can raise the limit:

app.use(express.json({ limit: '1mb' }));

Setting a limit too high may expose your app to Denial‑of‑Service attacks, so choose a value that balances functionality and safety.

By default only application/json is accepted. If you need to parse application/vnd.api+json or other custom media types, supply the type option:

app.use(express.json({
  type: ['application/json', 'application/vnd.api+json']
}));

Alternatively, use a function to evaluate the request object:

app.use(express.json({
  type: (req) => req.headers['content-type'] === 'application/json' ||
                  req.headers['content-type'] === 'application/vnd.api+json'
}));

Verifying Raw Bodies for Webhooks

Some services sign the raw request body (e.g., Stripe, GitHub). The verify callback receives the raw buffer before parsing:

app.use(express.json({
  verify: (req, res, buf, encoding) => {
    req.rawBody = buf.toString(encoding || 'utf8');
  }
}));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const isValid = validateSignature(req.rawBody, signature);
  if (!isValid) {
    return res.status(400).send('Invalid signature');
  }
  // Process parsed JSON in req.body
  res.send('OK');
});

Storing the raw body increases memory usage for large payloads, so use it only when necessary.

Migration Checklist and Common Pitfalls

• Remove body-parser from package.json and require statements.
• Verify Express version >= 4.16.0 with npm ls express.
• Ensure all routes that previously relied on bodyParser.json() now use express.json().
• Update any custom type or limit settings to match previous behavior.
• Test that clients sending JSON with the correct Content-Type still receive req.body populated.
• Check that requests lacking the header return undefined and do not crash your handlers.
• For multipart uploads, install a dedicated library like multer – express.json() will not parse multipart/form-data.

Common errors after migration:

1. 413 Payload Too Large – Occurs when the JSON body exceeds 100 KB. Increase the limit option or reject large payloads gracefully.
2. Undefined req.body – Often due to missing Content-Type: application/json header. Validate client requests or add a fallback middleware that sets a default header.
3. Signature verification failures – If you use verify, ensure the raw body is stored before parsing and that the encoding matches the webhook provider’s specification.

Wrap‑up

Switching to express.json() is a straightforward, dependency‑free upgrade that modernizes your Express stack. The middleware offers the same core features as body-parser with added flexibility: custom limits, type matching, and raw body verification. By following the migration checklist and watching for the common pitfalls, you can keep your API robust, secure, and up to date.

Remember: always test the new configuration against your existing clients and consider adding explicit content‑type validation in production to guard against malformed requests.