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

> Learn how to configure CORS for cross-origin API access in Astro-Big-Doc. Enable the cors middleware by setting the ENABLE_CORS environment variable to true.

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js), the logic appears as:

```javascript
// 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:

```dotenv

# .env

ENABLE_CORS=true

```

The server automatically loads this variable because [`server/server.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js) initializes **dotenv** at startup via `dotenv.config()`. No code changes are required.

### Verification

Start the development server:

```bash
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`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js) as follows:

```javascript
// 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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`:

```javascript
// 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`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js) based on the environment variable.
- **Customization:** Advanced users can modify [`server/server.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js).

### What file controls CORS configuration?

CORS configuration is controlled in **[`server/server.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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.