Config

Elegance by design comes with sensible defaults; but many of its options can and should be tweaked.

If you boostrapped your project, you should have an elegance.config.ts file; with not much in it.

If no overrides are given, the default values are interpreted as such:

const defaultConfig: SafeEleganceConfig = {
    security: {
        contentSecurityPolicy: {
            defaultSrc: [],
            scriptSrc: ["'self'", "blob:"],
            scriptSrcElem: ["'self'", "blob:"],
            imgSrc: ["'self'", "data:", "https:"],
            fontSrc: [],
            connectSrc: [],
            frameSrc: ["'none'"],
            objectSrc: ["'none'"],
            baseUri: ["'self'"],
            formAction: ["'self'"],
            upgradeInsecureRequests: false,
        },
        strictTransportSecurity: {
            maxAge: 31536000,
            includeSubDomains: true,
        },
        xFrameOptions: "DENY",
        xContentTypeOptions: true,
        referrerPolicy: "strict-origin-when-cross-origin",
        permissionsPolicy: {
            camera: ["'none'"],
            microphone: ["'none'"],
            geolocation: ["'none'"],
        },
        crossOriginOpenerPolicy: "same-origin",
        crossOriginResourcePolicy: "same-origin",
        xDnsPrefetchControl: "off",
    },

    output: {
        outputDirectory: ".elegance",
        pagesDirectory: "pages",
        publicDirectory: "public",
    },

    image: {
        optimize: true,
        formats: ["webp"],
        quality: { webp: 75, png: 80, jpeg: 80 },
        viewports: [320, 375, 414, 768, 1024, 1440, 1920, 2560, 3840],
        maxVariantsPerImage: 6,
        outDir: "/images",
    },

    server: {
        port: 3000,
        serveAPI: true,
        allowDynamicPages: true,
        allowStatusCodePages: true, 
    },

    console: {
        suppressEleganceLogs: false,
        clearConsoleOnRebuilds: true,
    },

    runtime: {
        hotReloadPort: 4000,
    },

    client: {
        viewTransitions: true,
    },

    bundling: {
        include: [],       // glob paths to force-bundle into client
        noBundle: [],      // glob paths to never include in client bundle
    }
};

Note: this structure is deep copied, so you can override just one field of a given sub-object and the others still follow their defaults.

List of Options

security

This section defines the security headers sent with requests. For convenience sake, developers shouldn't need to construct them; as they're 99% similar across most projects.

For example, when deploying to GitHub Pages, it may be favorable to set upgradeInsecureRequests to true; to permit things like client-side navigation.

output

These define the output options of your project, where Elegance reads from, and where it writes to.

The given paths are relative to where the project is being executed from.

image

These define the image optimization options for use with <Image/> components. outDir here is relative to config.outputDirectory/dist.

server

These define the Elegance Server's runtime options. If desired, you can suppress dynamic and statuscode pages from being rendered; as well as block all API routes from being processed.

console

These define what is to be written to the console during execution of the project. These apply only to logs that Elegance itself makes, not necessarily to logs you may add yourself.

It may be ideal to turn logging off for Elegance if you have it embedded within another project for example.

runtime

Here you can adjust the hot-reload port if required - though, it should be fine without the need to touch it.

client

These define the options for the client.js file shipped to the browser.

Disabling viewTransitions forbids the usage of the view-transition API in browsers during client-side navigation.

bundling

These let you decide bundling rules for package paths.

• include — glob paths (e.g. my-package/*, **/utils*) that will be force-bundled into the client bundle. Paths listed here behave as if //!allow-bundling was written above the import.

• noBundle — glob paths that will never be included in the client bundle. Reaching a banned path from client code causes a build error with a "Server Only File" message. Behaves as if //!no-bundle or //!no-bundle-file was used.

Packages can also self-declare via "elegance": { "bundle": [...], "no-bundle": [...] } in their package.json. Glob patterns (*, **, ?, [...]) are supported in all declarations.