Explore Terrastories

November 29, 2025 · View on GitHub

A web application for public exploration of community stories shared through Terrastories.

Overview

Explore Terrastories allows communities to share their place-based stories publicly. It connects to a Terrastories server API to display unrestricted stories that communities have opted to share.

Built with:

React + TypeScript
MapLibre GL JS with Protomaps for mapping
Vite for build tooling
Axios for API requests

📚 Documentation: docs.terrastories.app

Prerequisites

Node.js 20+
A running Terrastories server with API access

Setup

1. Install Dependencies

npm install

2. Configure API Connection

Create a .env file with your Terrastories API endpoint:

VITE_API_BASE=https://your-terrastories-server.com

3. Configure CORS

Add your Explore Terrastories host to the CORS_ORIGINS variable in your Terrastories server's .env.api file:

CORS_ORIGINS=http://localhost:1080,https://your-explore-domain.com

Development

Start the development server:

npm run dev

Open http://localhost:1080 to view the app.

Testing

# Run unit tests
npm test

# Run E2E tests
npm run test:e2e

# Run E2E tests with UI
npm run test:e2e:ui

# Type checking
npm run lint

Deployment

Build for Production

npm run build

The optimized build will be output to the dist/ folder.

Preview Production Build

npm run serve

GitHub Pages

Deployment to GitHub Pages happens automatically on push to main via GitHub Actions.

Project Structure

src/
├── components/     # React components
├── utils/          # Utility functions
├── translations/   # i18n translations
└── setupTests.ts   # Test configuration

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main branch.

License

See LICENSE file for details.

Terrastories - Main application
Terrastories Documentation - User guides and support

Developed by Awana Digital