Custom Query Parser in Express

Jun 26, 2025

I was looking for a way to support dot notation in the parameters of my query string in my HTTP endpoint. For example, /search?user.name=Bruno&car.name=Honda+Civic. I wanted req.query to be parsed in a structured way so that I could do

const {
  user: { name: userName } = {},
  car: { name: carName } = {},
} = req.query;

It turns out you can set a custom query parser in your Express app. Additionally, qs, a query string parser already used in Express, supports the dot notation. Here’s how to implement it:

const app = express();

// Use custom query parser
app.set('query parser', (str: string) => qs.parse(str, { allowDots: true }));

Here’s a simple demo implementation:

import express, { Request, Response } from 'express';
import * as qs from 'qs';

const app = express();

// Use custom query parser
app.set('query parser', (str: string) => qs.parse(str, { allowDots: true }));

interface SearchQuery {
  user?: {
    name?: string;
  };
  car?: {
    name?: string;
  };
}

app.get('/search', (req: Request<{}, {}, {}, SearchQuery>, res: Response) => {
  const {
    user: { name: userName } = {},
    car: { name: carName } = {},
  } = req.query;

  if (userName) {
    console.log('User name:', userName);
  }
  if (carName) {
    console.log('Car name:', carName);
  }

  res.json({ userName, carName });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

#express #nodejs #typescript #query-string