Observable Framework

Observable Framework consists of three core components:

1. Local development server: Provides a preview of your application locally with instant updates as you save changes.
2. Static site generator: Compiles Markdown, JavaScript, assets, and data snapshots (generated by loaders) into a static site suitable for hosting anywhere.
3. Command-line interface (CLI): Automates builds and deployments to share your application securely.

Observable Framework (or "Framework") is an open-source static-site generator designed specifically for building data apps. Data apps are applications focused on displaying data to help users derive insights or evaluate decisions.

Common use cases include:

• Interactive visualizations for self-service analysis.
• Live dashboards that contextualize current events with historical trends.
• Point-in-time reports combining graphics and prose for in-depth analysis.

Framework is designed to be highly customizable via code, allowing for integration into existing professional workflows (editors, source control, CI/CD, unit testing, and self-hosting).

Files referenced via FileAttachment in your src directory are automatically detected during build and copied to the dist/_file folder.

Key behaviors:

• Content Hashing: Files are renamed with a content hash (e.g., quakes.e5f2eb94.csv) to enable cache breaking. The framework automatically rewrites your code references to match these hashed names.
• Static Analysis: Only files explicitly referenced via static string literals in FileAttachment are included in the build. This prevents unused assets from bloating your deployment.
• Automatic Promotion: Certain HTML elements like audio, img, link, picture, and video automatically promote their src or href assets to file attachments in the _file folder.

This example uses Observable Plot to visualize Google Analytics data. The dashboard includes:

• Key metric numbers
• Line and area charts
• Horizon charts (faceted by channel for active users)
• Marimekko charts (for 'new vs. returning' users)
• Punchcard charts (for activity by day and hour)

The implementation details for these charts can be found in src/index.md.

This example demonstrates how to write a TypeScript data loader in Observable Framework that queries Elasticsearch using the Elasticsearch Node.js client.

In this implementation:

• The data loader logic is located in src/data/kibana_sample_data_logs.csv.ts.
• A helper client is provided in src/data/es_client.ts to manage the connection.

The project follows a standard Observable Framework structure with no external dependencies required beyond the Framework itself. Key directories include:

• src/components/: Reusable visualization components.
• src/data/: Local data files (e.g., .csv).
• src/index.md: The main entry point for the dashboard.
• observablehq.config.js: Framework configuration.

.
├── README.md
├── observablehq.config.js
├── package.json
└── src
    ├── components
    │   ├── bigNumber.js
    │   └── donutChart.js
    ├── data
    │   ├── hotelData.csv
    └── index.md

The repository provides two distinct categories of examples to help you build data apps:

1. Technique examples: Smaller, piecemeal examples focused on specific development tasks (e.g., "how to load data from Google Analytics" or "how to make a bump chart"). These are intended for copy-pasting reusable code into your project.
2. Showcase examples: Larger, complete applications that demonstrate how multiple techniques work together to solve high-level user needs (e.g., "how to analyze website traffic"). These are intended for inspiration and demonstrating the full potential of the Framework.

Framework uses a static-site architecture to ensure high performance for data-heavy applications:

• Precomputed Data: Data is computed at build time, ensuring the client receives highly-optimized, aggregated, or anonymized snapshots.
• Security: Because data loaders run only during the build process, end-users do not need direct access to underlying data sources, making dashboards more secure.
• Rapid Prototyping: Data loaders allow you to shortcut warehouse changes by pulling data directly into the build process to validate ideas quickly.