Document common cors configuration issues

[markphelps]

we had a user in discord note that CORS config wasnt working with their browser based app (Vue) when trying to issue a client side evaluation request using the official Flipt JS SDK:

---

Conversation:

I have Flipt v2 running locally using the following config

credentials:
  github-api:
    access_token: {REDACTED}
    type: access_token
cors:
  enabled: false
environments:
  default:
    default: true
    directory: flipt
    name: default
    scm:
      credentials: github-api
      type: github
    storage: default
storage:
  default:
    backend:
      type: memory
    branch: main
    credentials: github-api
    poll_interval: 30s

but when my client makes this request, it's getting rejected for CORS. What am I doing wrong here?
http://localhost:8080/internal/v1/evaluation/snapshot/namespace/default

<template>flag is {{ flagState }}</template>

<script setup lang="ts">
import { FliptClient } from '@flipt-io/flipt-client-js';
import { onMounted, ref } from 'vue';
const flagState = ref(false);
onMounted(async () => {
  try {
    const client = await FliptClient.init({
      namespace: 'default',
      url: 'http://localhost:8080/',
    });
    const response = client.evaluateBoolean({
      flagKey: 'sdf',
      entityId: 'someentity',
      context: {
        fizz: 'buzz',
      },
    });
    console.log('Flag evaluation response:', response);
    flagState.value = response.enabled;
  } catch (error) {
    console.error('Error initializing Flipt client:', error);
  }
});
</script>

I'm using Vue and the official SDK

---

They said that even when they set cors.enabled to true, it still didnt fix the issue. They were on the Microsoft Edge Browser (latest version).

What did eventually work was when they configured the cors config explicitly, instead of relying on the defaults like:

cors:
  enabled: true
  allowed_origins:
    - http://localhost:5173
  allowed_methods: [GET, POST, OPTIONS]
  allowed_headers:
    - Content-Type
    - Authorization
    - X-Requested-With
    - x-flipt-environment

We should document some common issues when configuring CORS and how to fix them

[markphelps]

@claude can you update the v2 docs to document how users may need to set the allowed_origins and other configuration options when enabling cors if the defaults dont work?

I think we should do this on the v2/configuration/overview page and maybe break CORS config into its own table? Then we could put the the new section about configuring cors beyond the defaults under this table? IDK think about where this info should go and how it should be worded before implementing the change

[claude]

Claude finished @markphelps's task —— View job • claude/issue-350-20250815-1958 • Create PR ➔

---

Documenting CORS Configuration Issues

I've successfully updated the v2 configuration documentation to help users troubleshoot CORS configuration issues.

Tasks:

• Read repository guidelines and current documentation structure
• Examine v2/configuration/overview page
• Enhance CORS configuration documentation
• Add troubleshooting section for common CORS issues
• Run linting and formatting
• Commit and push changes

Changes Made:

Enhanced CORS Documentation:

• Created a dedicated CORS section with its own table (breaking it out from the general configuration parameters)
• Added the missing cors.allowed_methods property that was referenced in the issue
• Improved descriptions and formatting

Added Troubleshooting Section:

• Documented the common issue where cors.enabled: true alone isn't sufficient
• Provided a practical solution with explicit configuration examples
• Included specific examples for Vue (port 5173), React (port 3000), and production domains
• Added guidance about client-side SDKs like the Flipt JavaScript SDK

Configuration Example:

cors:
  enabled: true
  allowed_origins:
    - http://localhost:3000 # React development server
    - http://localhost:5173 # Vite development server
    - https://yourapp.com # Production domain
  allowed_methods:
    - GET
    - POST
    - OPTIONS
  allowed_headers:
    - Content-Type
    - Authorization
    - X-Requested-With
    - x-flipt-environment

The documentation now directly addresses the issue reported by the Discord user and provides clear guidance for browser-based applications using the Flipt JS SDK.

---