How to Configure CORS for Allowing Cross-Origin API Access in Astro-Big-Doc

Set the environment variable ENABLE_CORS to "true" in your .env file or deployment environment to activate the cors middleware in the Express server.

Astro-Big-Doc runs an Express server (server/server.js) to serve generated static sites and optional API endpoints. By default, cross-origin requests are blocked to prevent unauthorized external access. You can configure CORS for allowing cross-origin API access using a declarative environment flag without modifying source code.

How CORS Works in Astro-Big-Doc

The CORS implementation relies on conditional middleware loading in the main server file. When the server starts, it checks for the ENABLE_CORS environment variable before applying the middleware.

In server/server.js, the logic appears as:

// server/server.js
import cors from 'cors';
// ...
if (process.env.ENABLE_CORS == "true") {
    app.use(cors());      // activates CORS for every route
    console.log("\n -- !!! CORS enabled !!! -- APIs can be used from other sites --\n")
}

Default behavior: The middleware is not applied when the variable is unset or set to any value other than "true", causing browsers to block requests from other origins.

Enabling CORS via Environment Variables

Basic Configuration

Create or edit a .env file at the project root:

# .env

ENABLE_CORS=true

The server automatically loads this variable because server/server.js initializes dotenv at startup via dotenv.config(). No code changes are required.

Verification

Start the development server:

npm install
npm run dev

The console will output:

 -- !!! CORS enabled !!! -- APIs can be used from other sites --

This confirms that the cors middleware is active and cross-origin API access is permitted.

Customizing CORS Options for Production

For stricter security, you can restrict origins, methods, or credentials by passing an options object to the cors middleware. Modify server/server.js as follows:

// server/server.js
import cors from 'cors';

// Define custom options
const corsOptions = {
  origin: 'https://example.com',
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  credentials: true,
};

// Apply only when CORS is enabled
if (process.env.ENABLE_CORS == "true") {
  app.use(cors(corsOptions));
  console.log("\n -- !!! CORS enabled with custom options !!! --\n");
}

Note: The cors package is already a direct dependency in package.json, so no additional installation is required.

Testing Cross-Origin API Access

Once enabled, test from a different origin using a browser console or fetch:

// Test request from https://other-domain.com
fetch('https://your-astro-big-doc-api.com/api/data', {
  method: 'GET',
  credentials: 'include'
})
.then(response => response.json())
.then(data => console.log(data));

If CORS is properly configured, the request succeeds. If disabled, the browser throws a CORS policy error.

Summary

• Default state: CORS is disabled in Astro-Big-Doc to block cross-origin requests.
• Activation method: Set ENABLE_CORS=true in your .env file or deployment environment.
• Implementation location: The cors middleware is conditionally applied in server/server.js based on the environment variable.
• Customization: Advanced users can modify server/server.js to pass specific cors options for origin whitelisting and method restrictions.

Frequently Asked Questions

Is CORS enabled by default in Astro-Big-Doc?

No. CORS is disabled by default in Astro-Big-Doc. The server only applies the cors middleware when the ENABLE_CORS environment variable is explicitly set to "true". Without this flag, browsers block all cross-origin API requests.

How do I restrict CORS to specific domains only?

To restrict access to specific domains, modify server/server.js to pass a configuration object to the cors middleware instead of calling cors() with no arguments. Set the origin property to your allowed domain(s), such as origin: 'https://example.com'. This overrides the default permissive behavior that allows all origins when ENABLE_CORS is enabled without custom options.

Can I enable CORS without modifying code?

Yes. You can enable CORS purely through configuration by setting the ENABLE_CORS environment variable to "true" in your .env file or deployment platform (e.g., Vercel, Netlify, or Docker environment variables). The server reads this variable at startup and automatically applies the cors middleware without requiring any changes to server/server.js.

What file controls CORS configuration?

CORS configuration is controlled in server/server.js, which is the main Express server file. This file contains the conditional logic that checks process.env.ENABLE_CORS and applies the cors middleware. For environment-based configuration, the .env file (or .env.example for templates) controls whether CORS is enabled by defining the ENABLE_CORS variable.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}