---
title: 'Installation'
description: 'Create a new Ecopages project by installing the core package and your chosen rendering integration.'
order: 2
---

import { CodeTabs } from '@/components/code-tabs';

# Installation

To create a new Ecopages project, install the core package plus the rendering integration you want to start with. The example below uses Ecopages JSX for standard `.tsx` routes.

<CodeTabs
	name="getting-started-installation"
	tabs={[
		{
			id: 'npm',
			label: 'npm',
			code: 'npm install @ecopages/core @ecopages/ecopages-jsx @ecopages/jsx @ecopages/radiant',
		},
		{
			id: 'pnpm',
			label: 'pnpm',
			code: 'pnpm add @ecopages/core @ecopages/ecopages-jsx @ecopages/jsx @ecopages/radiant',
		},
		{
			id: 'bun',
			label: 'bun',
			code: 'bun add @ecopages/core @ecopages/ecopages-jsx @ecopages/jsx @ecopages/radiant',
		},
	]}
	defaultSelectedKey="npm"
/>

This example installs the default stack: the core package plus Ecopages JSX and its peer runtimes. Register React, Lit, standalone MDX, or KitaJS when those Integrations should own routes.

## Configuration

After installation, create an `eco.config.ts` file in your project's root directory to configure Ecopages. This file defines your site's structure, integrations, and canonical base URL.

```typescript
// filepath: eco.config.ts
import { defineConfig } from '@ecopages/core/config';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';

export default defineConfig({
	rootDir: import.meta.dirname,
	baseUrl: 'https://your-production-domain.com',
	integrations: [ecopagesJsxPlugin()],
});
```

### Environment Variables

Ecopages uses environment variables for configuration overrides. Create a `.env` file in your project root (and add it to `.gitignore`).

```bash
# filepath: .env.example
# Overrides the baseUrl set in eco.config.ts (e.g., for different deployment stages)
ECOPAGES_BASE_URL=https://staging.your-production-domain.com

# Overrides the hostname the server listens on (Default: localhost)
ECOPAGES_HOSTNAME=0.0.0.0

# Overrides the port the server listens on (Default: 3000)
ECOPAGES_PORT=8080

# Enable debug logging (Default: false)
ECOPAGES_LOGGER_DEBUG=true
```

**Configuration Precedence:**

- **Server Hostname/Port:** Constructor `serverOptions` > Environment Variables (`ECOPAGES_HOSTNAME`, `ECOPAGES_PORT`) > Defaults (`localhost:3000`).
- **Canonical Base URL:** `eco.config.ts` (`setBaseUrl`) > Environment Variable (`ECOPAGES_BASE_URL`) > Default (`http://localhost:3000`).

## Project Structure

A typical Ecopages project structure looks like this:

```

my-project/
├── src/
│ ├── pages/
│ ├── layouts/
│ ├── components/
│ └── includes/
├── public/
├── app.ts # Your application entry point
├── eco.config.ts # Ecopages configuration
├── package.json
└── .env # Environment variables (optional)

```

- `src/pages/`: Contains your page files (e.g., `.tsx`, `.mdx`, `.kita.tsx`, `.lit.tsx`)
- `src/layouts/`: Holds layout components
- `src/components/`: Stores reusable components
- `src/includes/`: Contains include templates (e.g., `head.tsx`, `html.tsx` or integration-specific suffixes)
- `public/`: Static assets that will be copied to the build directory
- `app.ts`: The main script to run Ecopages commands.
- `eco.config.ts`: Ecopages configuration file.

## Usage

Create an entry point file (e.g., `app.ts`) to initialize and run Ecopages:

```typescript
// filepath: app.ts
import { createApp } from '@ecopages/core/create-app';

const app = await createApp();
await app.start();
```

Add the following scripts to your `package.json`:

```json
{
	"scripts": {
		"build": "ecopages build",
		"dev": "ecopages dev",
		"preview": "ecopages preview",
		"start": "ecopages start",
		"watch:dev": "ecopages dev:watch"
	}
}
```

Now you can use these commands:

- `pnpm run dev` (or `bun run dev`): Starts the development server. You can override the host, port, base URL, and runtime with CLI flags or environment variables.
- `pnpm run build` (or `bun run build`): Builds your project for production into the `dist` directory.
- `pnpm run start` (or `bun run start`): Starts the production server from the existing `dist` build output.
- `pnpm run preview` (or `bun run preview`): Rebuilds `dist` and then serves that production output locally for verification.

## Next Steps

With Ecopages installed and configured, you're ready to start building your site. Check out the [Pages](/docs/core/pages) guide to learn how to create content using different integrations.