Welcome to HacheQL ·
HacheQL is a JavaScript library that brings HTTP caching to your GraphQL API.
- Automatically creates and caches persisted GraphQL queries.
- Integrates with any server running on Node.js.
- Includes specialized support for servers written with Express.js.
- Supports caching with Redis or in the server's local memory.
Check out our demo site to see what HacheQL can do.
HacheQL sends GraphQL requests in a way that makes the response HTTP cacheable, so subsequent requests for the same data can be fulfilled from a cache in the browser or on a proxy server.
HacheQL works by hashing the contents of GraphQL queries and caching key-value pairs of the form <hashed query>: <full query> on the server side.
Let's get the server set up first.
HacheQL works with any Node.js server, but it includes specialized support for servers written in Express.js. If your project uses Express, see the next section, titled 'Server-side HacheQL - with Express.'
If you use vanilla Node or a different Node framework, you're in the right place.
Expand for instructions
- Install HacheQL with npm.
npm install hacheql
- Import
nodeHacheQL
in files that handle GraphQL requests.
import { nodeHacheQL } from 'hacheql/server';
- Call
nodeHacheQL
as the first step in handling GraphQL requests.
server.on('request', async (req, res) => {
if (request.url === '/graphql') {
try {
const query = await nodeHacheQL(req, res, { redis: redisClient });
const data = await database.query(query);
res.end(data);
} catch (error) {
/* error handling logic */
}
}
});
See the Documentation for more detail on how to use this function.
That's all for the server! See Client-side HacheQL for the next steps.
If your project uses Express, this section is for you. If not, see the previous section, titled 'Server-side HacheQL.'
Expand for instructions
- Install HacheQL with npm.
npm install hacheql
- Import
expressHacheQL
andhttpCache
in files that handle GraphQL requests.
import { expressHacheQL, httpCache } from 'hacheql/server';
- Use
expressHacheQL
as the first piece of middleware in routes that handle GraphQL requests.
If you want to cache using Redis, pass expressHacheQL
an object with a property redis
whose value is a reference to your Redis client.
app.use('/graphql', expressHacheQL({ redis: <redisClient> }), /* other middleware */);
If you aren't using Redis, don't pass any arguments to expressHacheQL
and it will automatically use the server's memory for caching.
app.use('/graphql', expressHacheQL(), /* other middleware */);
- Use
httpCache
prior to sending a response.
app.use(
'/graphql',
expressHacheQL(),
httpCache(),
graphqlHTTP({ schema, graphiql: true,}),
);
expressHacheQL
relies on Express's built-in express.json() method for parsing JSON-encoded request bodies. If you don't have it set up yet, add the following toward the top of your main server file:
app.use(express.json())
That's all for the server! Let's set up the client.
HacheQL's client side is the same whether or not your server uses Express, and it's very simple to set up.
Note: It's possible to implement HacheQL on the client-side gradually. You can set it up for some GraphQL routes and not for others, and everything will still work.
Expand for instructions
- Import
hacheQL
in files that send requests to a GraphQL API.
import { hacheQL } from 'hacheql';
- HacheQL is designed to make it easy to switch over from the Fetch API. All you have to do is replace the word
fetch
with the wordhacheQL
. The arguments to the function remain exactly the same.
For example, here's how you might send a GraphQL request using the Fetch API:
fetch('/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/graphql' },
body: '{ hero { name } }'
})
.then(/* code */)
And here's what that same request looks like using HacheQL:
hacheQL('/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/graphql' },
body: '{ hero { name } }'
})
.then(/* code */)
Simply replace fetch
with hacheQL
wherever the client-side code queries the GraphQL API, and you're done! You've set up HTTP caching for your GraphQL requests.
Check out the Documentation for more sample usage, technical details, and ways to customize behavior.
If you'd like to contribute, read our Contributing Guide.
HacheQL is MIT Licensed.