Parsing and Formatting HTTP Headers: content-disposition vs content-type

Both content-disposition and content-type solve focused problems in HTTP communication: they handle the parsing and formatting of two critical but distinct headers. While they share similar design philosophies — small, zero-dependency, spec-compliant utilities — they operate on entirely different parts of the HTTP protocol. Let’s examine how they differ in purpose, API, and real-world usage.

📥 What Each Package Handles: Different Headers, Different Jobs

content-disposition works exclusively with the Content-Disposition header. This header tells browsers how to handle the response body — whether to display it inline (inline) or prompt a file download (attachment). It also carries filename information.

// content-disposition: Creating a download header
const contentDisposition = require('content-disposition');
const header = contentDisposition('report.pdf', { type: 'attachment' });
// Result: 'attachment; filename="report.pdf"'

content-type deals only with the Content-Type header. This header defines the media type of the resource (e.g., text/plain, application/json) and may include parameters like charset=utf-8.

// content-type: Parsing a Content-Type header
const contentType = require('content-type');
const parsed = contentType.parse('application/json; charset=utf-8');
// Result: { type: 'application/json', parameters: { charset: 'utf-8' } }

These packages never overlap in functionality — you’ll often use both in the same application, just for different tasks.

🔧 Core APIs: Formatting vs Parsing Emphasis

While both packages support parsing and formatting, their primary strengths differ based on typical usage patterns.

Generating Headers

content-disposition shines when generating safe, RFC-compliant Content-Disposition headers, especially with filenames containing spaces or non-ASCII characters:

// content-disposition handles tricky filenames
const header = contentDisposition('résumé.txt');
// Result: 'inline; filename="resume.txt"; filename*=UTF-8\'\'r%C3%A9sum%C3%A9.txt'

content-type focuses on parsing existing Content-Type headers reliably, but can also format them:

// content-type formatting
const formatted = contentType.format({
  type: 'text/html',
  parameters: { charset: 'utf-8' }
});
// Result: 'text/html; charset=utf-8'

Parsing Headers

content-disposition can parse headers too, though this is less common:

// content-disposition parsing
const parsed = contentDisposition.parse('attachment; filename="data.csv"');
// Result: { type: 'attachment', parameters: { filename: 'data.csv' } }

content-type excels at parsing, automatically normalizing and validating input:

// content-type strict parsing
try {
  const parsed = contentType.parse('application/json; charset=utf-8');
} catch (err) {
  // Throws if header is invalid
}

⚠️ Error Handling Philosophy

Both packages throw errors on malformed input during parsing, but their tolerance differs slightly.

content-disposition will throw if the header doesn’t conform to expected syntax:

// This throws
try {
  contentDisposition.parse('invalid header');
} catch (err) {
  // TypeError: invalid Content-Disposition
}

content-type is similarly strict but provides clearer error messages about what part of the header failed:

// This throws
try {
  contentType.parse('not-a-type');
} catch (err) {
  // TypeError: invalid media type
}

Neither package attempts to “fix” bad input — they enforce correctness by design.

🌐 Real-World Usage Scenarios

Serving Downloadable Files

When implementing a file download endpoint, you’ll use content-disposition to set the correct header:

// Express.js example
app.get('/download/:filename', (req, res) => {
  const header = contentDisposition(req.params.filename, { type: 'attachment' });
  res.set('Content-Disposition', header);
  // ... send file
});

You might also use content-type in the same handler to ensure the correct MIME type:

const mimeType = getMimeType(req.params.filename); // e.g., 'text/csv'
res.set('Content-Type', contentType.format({ type: mimeType }));

Validating API Requests

When building an API that expects JSON, use content-type to verify the request:

// Middleware to check Content-Type
function jsonOnly(req, res, next) {
  try {
    const parsed = contentType.parse(req.headers['content-type']);
    if (parsed.type !== 'application/json') {
      return res.status(400).send('JSON only');
    }
    next();
  } catch (err) {
    return res.status(400).send('Invalid Content-Type');
  }
}

You wouldn’t use content-disposition here — it’s irrelevant to request validation.

📦 When You Need Both Together

In file upload/download systems, you’ll often combine both:

// File download endpoint
app.get('/files/:id', async (req, res) => {
  const file = await getFile(req.params.id);
  
  // Set Content-Type
  res.set('Content-Type', contentType.format({ type: file.mimeType }));
  
  // Set Content-Disposition
  res.set('Content-Disposition', 
    contentDisposition(file.originalName, { type: 'attachment' })
  );
  
  res.send(file.data);
});

Each package handles its own header without interference.

🛑 Common Misconceptions

• Myth: “I can use content-type to handle file downloads.”

  • Reality: Content-Type tells the browser what the file is, but Content-Disposition tells it what to do with it. Both are needed for proper file handling.

• Myth: “These packages work in browsers.”

  • Reality: They’re designed for Node.js server environments where you control HTTP headers. Browsers don’t let you set arbitrary response headers.

💡 Key Takeaways

🆚 Final Recommendation

Don’t think of these as competitors — they’re teammates. Use content-disposition whenever you’re serving files that should be downloaded or displayed inline with custom filenames. Use content-type whenever you need to inspect or set the media type of a resource. In most web applications that handle file I/O, you’ll end up using both, each doing its own job precisely and without overlap.