Static Files

Introduction

Loly Framework provides a simple way to serve static files like images, fonts, robots.txt, sitemap.xml, and other assets through the public/ directory.

Files placed in the public/ directory are served directly at the root URL path and have priority over dynamic routes.

This is particularly important for SEO, as it allows search engines like Google to find files such as sitemap.xml and robots.txtat their standard locations.

Public Directory

The public/ directory is configured in yourloly.config.ts file. You can use partial configuration and only specify what you want to change:

import type { FrameworkConfig } from "@lolyjs/core";

// Partial configuration (recommended)
export default {
  directories: {
    static: "public",  // Default: "public"
  },
} satisfies Partial<FrameworkConfig>;

If you don't specify the static directory, the framework uses "public" by default.

Any file you place in the public/ directory will be accessible at the root URL. For example:

Route Priority

Static files have priority over dynamic routes. This is a fundamental part of how Loly Framework handles requests:

Request Flow:

1. HTTP Request arrives at the server
2. Static files check - The server first checks if a static file exists in public/ for the requested path
3. If a static file is found, it's served immediately (no route matching occurs)
4. If no static file is found, the router attempts to match dynamic routes

This means:

• If you have public/robots.txt, it will be served at /robots.txt even if you have a route atapp/robots.txt/page.tsx
• Static files are checked before the router attempts to match dynamic routes
• This ensures that important static files like robots.txtand sitemap.xml are always accessible at their standard locations for SEO purposes

Important: Avoid creating page routes with names that conflict with static files you want to serve. For example, if you havepublic/sitemap.xml, don't createapp/sitemap.xml/page.tsx as the static file will always take precedence and the page route will never be reached.

Common Use Cases

Here are some common use cases for static files:

SEO Files

Place SEO-related files in the public directory:

public/
  robots.txt     # /robots.txt
  sitemap.xml    # /sitemap.xml
  favicon.png    # /favicon.png (or favicon.ico)

Note: The favicon must be placed in the public/ directory. You can use either favicon.png or favicon.ico, and it will be automatically served at /favicon.png or/favicon.ico respectively.

Images and Assets

Organize images and other assets in subdirectories:

public/
  images/
    logo.png      # /images/logo.png
    hero.jpg      # /images/hero.jpg
  fonts/
    custom.woff2  # /fonts/custom.woff2

Manifest Files

PWA manifest and other configuration files:

public/
  manifest.json   # /manifest.json
  .well-known/
    security.txt  # /.well-known/security.txt

Best Practices

• Use static files for truly static content: Files that don't change based on user requests or don't need server-side processing. Static files are served directly without any server-side execution.
• Keep the public directory organized: Use subdirectories to organize different types of assets (images, fonts, etc.) for better maintainability.
• Don't use public for dynamic content: If you need to generate content dynamically (like a sitemap with dynamic URLs that change based on your content), use API routes instead. Static files are served as-is without any processing.
• Avoid naming conflicts: Don't create page routes that conflict with static files you want to serve. Remember that static files always take precedence.
• Optimize assets: Compress images and use modern formats (WebP, AVIF) for better performance. Static files are served directly, so their size directly affects load times.
• SEO files belong in public: Files like robots.txt,sitemap.xml, and favicon.png orfavicon.ico should be in the public directory to ensure search engines can find them at standard locations.