Elysia Helmet

3.1.0 · active · verified Wed Apr 22

Elysia Helmet is a security plugin for the Elysia web framework, designed to protect applications by setting various HTTP response headers. It functions as a direct port of the well-known `helmet` middleware from the Express ecosystem, adapting its battle-tested security configurations to the modern Elysia runtime. The current stable version is 3.1.0. Given its nature as a framework-specific plugin, its release cadence is closely aligned with updates to the Elysia framework itself and the upstream `helmet` project, ensuring continuous compatibility and incorporating the latest web security best practices. Its primary differentiator is providing a familiar and comprehensive suite of HTTP security headers specifically integrated for Elysia, enabling developers to easily apply crucial security measures without manual header management.

Common errors

```
Cannot find module 'elysia-helmet' or its corresponding type declarations.
```
cause The 'elysia-helmet' package has not been installed, or the import path is incorrect, or TypeScript is not configured to resolve modules correctly.

fix Install the package: `bun add elysia-helmet` (or `npm install elysia-helmet`, `yarn add elysia-helmet`). Verify the import statement: `import { helmet } from 'elysia-helmet';`
```
TypeError: app.use is not a function (or similar Elysia method not found)
```
cause This error typically indicates that the Elysia instance is not correctly initialized or the Elysia framework version is too old to support the plugin's API.

fix Ensure you are importing `Elysia` from 'elysia' correctly and that your Elysia version meets the 'elysia-helmet' peer dependency (`>= 1.2.0`). Update Elysia if necessary: `bun add elysia@latest`.
```
Property 'contentSecurityPolicy' does not exist on type 'HelmetOptions'.
```
cause The type definition for `HelmetOptions` might not include the property, or the property is nested differently than expected, or a specific `helmet` middleware is not enabled by default.

fix Check the `elysia-helmet` source code or the upstream `helmet` documentation for the correct structure of configuration options. Ensure you are using the correct version of `elysia-helmet` that supports the desired options.

Warnings

breaking elysia-helmet has a peer dependency on 'elysia' version '>= 1.2.0'. Using an older version of Elysia may lead to runtime errors or unexpected behavior.
Fix: Ensure your project's Elysia dependency is updated to version 1.2.0 or higher: `bun add elysia@latest`.
gotcha While a port of the original 'helmet' for Express, elysia-helmet may not have 100% identical feature parity or configuration options. Always refer to the elysia-helmet documentation or source code for specific Elysia-context configurations.
Fix: Consult the elysia-helmet GitHub repository and examples for the most accurate usage and configuration details within the Elysia framework.
gotcha Misconfiguring security headers, especially Content Security Policy (CSP), can inadvertently block legitimate content or scripts, leading to broken website functionality or user experience issues.
Fix: Thoroughly test your application with configured security headers in various browsers. Start with a more permissive CSP and gradually tighten directives while monitoring browser console errors.

Install

npm install elysia-helmet npm
yarn add elysia-helmet yarn
pnpm add elysia-helmet pnpm

Imports

helmet
wrong:
```
const helmet = require('elysia-helmet').helmet;
```
correct:
```
import { helmet } from 'elysia-helmet';
```
Elysia-Helmet is designed for ESM, preferring named imports. CommonJS require is not the idiomatic way to use this plugin.
helmet
wrong:
```
import helmet from 'elysia-helmet';
```
correct:
```
import { helmet } from 'elysia-helmet';
```
The 'helmet' function is a named export, not a default export. Using a default import will result in an undefined value.
HelmetOptions
```
import type { HelmetOptions } from 'elysia-helmet';
```
Import types explicitly for type-checking when configuring the plugin. Not needed for runtime.

Quickstart

Demonstrates how to install and integrate elysia-helmet into an Elysia application with basic security header configurations, including Content Security Policy, X-Content-Type-Options, and X-Frame-Options.

import { Elysia } from 'elysia';
import { helmet } from 'elysia-helmet';

const app = new Elysia()
  .use(helmet({
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'", "'unsafe-inline'"],
        imgSrc: ["'self'", 'data:'],
      },
    },
    xContentTypeOptions: true,
    xFrameOptions: { action: 'deny' },
  }))
  .get('/', () => 'Hello Elysia with Helmet!')
  .listen(3000);

console.log(`Server is running at ${app.server?.hostname}:${app.server?.port}`);

view raw JSON →