afv-library/skills/salesforce-webapp-configuring-webapp-metadata/SKILL.md

name	description
salesforce-webapp-configuring-webapp-metadata	Rules for web application metadata structure, webapplication.json configuration, and bundle organization. Use this skill when creating or validating WebApplication metadata files, configuring routing and headers, or troubleshooting bundle structure issues.

WebApplication Requirements

Bundle Rules

• A WebApplication bundle must live under webapplications/<AppName>/
• The bundle must contain <AppName>.webapplication-meta.xml
• The metadata filename must exactly match the folder name
• A build output directory must exist and contain at least one file
• Default build output directory: dist/
• If webapplication.json.outputDir is set, it overrides dist/

Valid example:

webapplications/
  MyApp/
    MyApp.webapplication-meta.xml
    webapplication.json
    dist/
      index.html

Metadata XML

Required fields:

• masterLabel
• version (max 20 chars)
• isActive (boolean)

Optional fields:

• description (max 255 chars)

webapplication.json

webapplication.json is optional.

Allowed top-level keys only:

• outputDir
• routing
• headers

File Constraints

• Must be valid UTF-8 JSON
• Max size: 100 KB
• Root must be a non-empty object
• Never allow {}, arrays, or primitives as the root

Path Safety

Applies to:

• outputDir
• routing.fallback

Reject:

• backslashes
• leading / or \
• .. segments
• null or control characters
• globs: *, ?, **
• %

All resolved paths must stay within the application bundle.

outputDir

• Must be a non-empty string
• Must reference a subdirectory only
• Reject . and ./
• The directory must exist in the bundle
• The directory must contain at least one file

routing

• If present, must be a non-empty object
• Allowed keys only:
  • rewrites
  • redirects
  • fallback
  • trailingSlash
  • fileBasedRouting

routing.trailingSlash

• Must be one of: "always", "never", "auto"

routing.fileBasedRouting

• Must be a boolean

routing.fallback

• Must be a non-empty string
• Must satisfy Path Safety rules
• Target file must exist

routing.rewrites

• Must be a non-empty array
• Each item must be a non-empty object
• Allowed keys: route, rewrite
• rewrite must be a non-empty string
• route, if present, must be a non-empty string

Example:

{
  "routing": {
    "rewrites": [
      { "route": "/app/:path*", "rewrite": "/index.html" }
    ]
  }
}

routing.redirects

• Must be a non-empty array
• Each item must be a non-empty object
• Allowed keys: route, redirect, statusCode
• redirect must be a non-empty string
• route, if present, must be a non-empty string
• statusCode, if present, must be one of: 301, 302, 307, 308

Example:

{
  "routing": {
    "redirects": [
      { "route": "/old-page", "redirect": "/new-page", "statusCode": 301 }
    ]
  }
}

headers

• If present, must be a non-empty array
• Each item must be a non-empty object
• Allowed keys: source, headers
• headers must be a non-empty array

Each header entry must contain:

• key: non-empty string
• value: non-empty string

Example:

{
  "headers": [
    {
      "source": "/assets/**",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

Never Suggest

• {} as the JSON root
• "routing": {}
• empty arrays
• empty array items such as [{}]
• "outputDir": "."
• "outputDir": "./"