diff --git a/reference/components/extension-api.md b/reference/components/extension-api.md index 5d729cf6..9845da3e 100644 --- a/reference/components/extension-api.md +++ b/reference/components/extension-api.md @@ -7,7 +7,9 @@ title: Extension API # Extension API -> As of Harper v4.6, a new iteration of the extension system called **Plugins** was released. Plugins simplify the API and are recommended for new extension development. See the [Plugin API](./plugin-api.md) reference. Both extensions and plugins are supported; extensions are not yet deprecated. + + +> As of Harper v4.6 and now stable in v5.0, a new iteration of the extension system called **plugins** was released. Plugins simplify the API and are recommended for new extension development. See the [Plugin API](./plugin-api.md) reference. Extensions are still supported as of v5.0 but are considered deprecated in favor of plugins. Extensions are components that provide reusable building blocks for applications. There are two key types: diff --git a/reference/components/overview.md b/reference/components/overview.md index aa5f7630..199ea208 100644 --- a/reference/components/overview.md +++ b/reference/components/overview.md @@ -22,21 +22,21 @@ title: Components **Applications** implement specific user-facing features or functionality. Applications are built on top of extensions and represent the end product that users interact with. For example, a Next.js application serving a web interface or an Apollo GraphQL server providing a GraphQL API are both applications. Also, a collection of Harper Schemas and/or custom Resources is also an application. -### Extensions - - +### Plugins -**Extensions** are the building blocks of the Harper component system. Applications depend on extensions to provide the functionality they implement. For example, the built-in `graphqlSchema` extension enables applications to define databases and tables using GraphQL schemas. The `@harperdb/nextjs` and `@harperdb/apollo` extensions provide building blocks for Next.js and Apollo applications respectively. + + -Extensions can also depend on other extensions. For example, `@harperdb/apollo` depends on the built-in `graphqlSchema` extension to create a cache table for Apollo queries. +**Plugins** are the building blocks of the Harper component system. Applications depend on plugins to provide the functionality they implement. For example, the built-in `graphqlSchema` plugin enables applications to define databases and tables using GraphQL schemas. The `@harperfast/nextjs` plugin provides the functionality to build a Next.js application on Harper. Plugins export a single `handleApplication` method and are always executed on worker threads. -### Plugins (Experimental) +Plugins can also depend on other plugins. For example, `@harperfast/nextjs` depends on the built-in `graphqlSchema` to create caching tables. - (experimental) +### Extensions -**Plugins** are a new iteration of the extension system introduced in v4.6. They are simultaneously a simplification and extensibility upgrade over extensions. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only export a single `handleApplication` method. + + -Plugins are **experimental**. In time extensions will be deprecated in favor of plugins, but both are currently supported. See the [Plugin API](./plugin-api.md) reference for complete documentation. +**Extensions** were replace by **plugins** in Harper v5; however, they are still supported for backwards compatibility. Extensions make use of the `start`, `startOnMainThread`, `handleFile`, `setupFile`, `handleDirectory`, and `setupDirectory` methods. ### Built-In vs. Custom Components diff --git a/reference/components/plugin-api.md b/reference/components/plugin-api.md index 69413101..6889f724 100644 --- a/reference/components/plugin-api.md +++ b/reference/components/plugin-api.md @@ -8,11 +8,12 @@ title: Plugin API # Plugin API - (experimental) + + -> The Plugin API is **experimental**. It is the recommended approach for building new extensions, and is intended to replace the [Extension API](./extension-api.md) in the future. Both systems are supported simultaneously. +**Plugins** are the building blocks of the Harper component system. Applications depend on plugins to provide the functionality they implement. For example, the built-in `graphqlSchema` plugin enables applications to define databases and tables using GraphQL schemas. The `@harperfast/nextjs` plugin provides the functionality to build a Next.js application on Harper. Plugins export a single `handleApplication` method and are always executed on worker threads. -The Plugin API is a new iteration of the extension system that simplifies the interface. Instead of defining multiple methods (`start`, `startOnMainThread`, `handleFile`, `setupFile`, `handleDirectory`, `setupDirectory`), a plugin exports a single `handleApplication` method. +Plugins can also depend on other plugins. For example, `@harperfast/nextjs` depends on the built-in `graphqlSchema` to create caching tables. ## Declaring a Plugin @@ -375,7 +376,7 @@ Function signature for the `'all'` event handler passed to `scope.handleEntry()` ## Example: Static File Server Plugin -A simplified form of the built-in `static` extension demonstrating key Plugin API patterns: +A simplified form of the built-in `static` plugin demonstrating key Plugin API patterns: ```js export function handleApplication(scope) { diff --git a/reference/database/data-loader.md b/reference/database/data-loader.md index 722eb2fa..6540b5e1 100644 --- a/reference/database/data-loader.md +++ b/reference/database/data-loader.md @@ -20,7 +20,7 @@ dataLoader: files: 'data/*.json' ``` -`dataLoader` is an [Extension](../components/extension-api.md) and supports the standard `files` configuration option, including glob patterns. +`dataLoader` is a [plugin](../components/plugin-api.md) and supports the standard `files` configuration option, including glob patterns. ## Data File Format @@ -213,4 +213,4 @@ Because the data loader uses content hashing, adding new countries or correcting - [Schema](./schema.md) — Defining table structure before loading data - [Jobs](./jobs.md) — Bulk data operations via the Operations API (CSV/JSON import from file, URL, or S3) -- [Components](../components/overview.md) — Extension and plugin system that the data loader is built on +- [Components](../components/overview.md) — Plugin system that the data loader is built on diff --git a/reference/index.md b/reference/index.md index 8617b40a..d7d6ed18 100644 --- a/reference/index.md +++ b/reference/index.md @@ -16,7 +16,7 @@ For concept introductions, tutorials, and guides, see the [Learn](/learn) sectio | -------------------------------------- | ----------------------------------------------------------------------- | | [Database](./database/overview.md) | Schema system, storage, indexing, transactions, and the database JS API | | [Resources](./resources/overview.md) | Custom resource classes, the Resource API, and query optimization | -| [Components](./components/overview.md) | Applications, extensions, the Plugin API, and the JS environment | +| [Components](./components/overview.md) | Applications, plugins, and the JS environment | ### Access & Security diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index 470b6883..f3d79241 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -573,7 +573,7 @@ Creates a new operation token from an existing refresh token. ## Components -Operations for deploying and managing Harper components (applications, extensions, plugins). +Operations for deploying and managing Harper components (applications, plugins). Detailed documentation: [Components Overview](../components/overview.md) diff --git a/reference/resources/overview.md b/reference/resources/overview.md index 4d4f3a49..d87e7b75 100644 --- a/reference/resources/overview.md +++ b/reference/resources/overview.md @@ -104,7 +104,7 @@ Resources are the true customization point for Harper. This is where the busines ## Exporting Resources as Endpoints -Resources become HTTP/MQTT endpoints when they are exported. As the examples demonstrated if a Resource extends an existing table, make sure to not have conflicting exports between the schema and the JavaScript implementation. Alternatively, you can register resources programmatically using `server.resources.set()`. See [HTTP API](../http/api.md) for server extension documentation. +Resources become HTTP/MQTT endpoints when they are exported. As the examples demonstrated if a Resource extends an existing table, make sure to not have conflicting exports between the schema and the JavaScript implementation. Alternatively, you can register resources programmatically using `server.resources.set()`. See [HTTP API](../http/api.md) for `server` API documentation. ## Pages in This Section diff --git a/src/components/VersionBadge.tsx b/src/components/VersionBadge.tsx index c3ace2e0..20c734c0 100644 --- a/src/components/VersionBadge.tsx +++ b/src/components/VersionBadge.tsx @@ -1,12 +1,13 @@ import React from 'react'; import styles from './VersionBadge.module.css'; -type VersionBadgeType = 'added' | 'changed' | 'deprecated'; +type VersionBadgeType = 'added' | 'changed' | 'deprecated' | 'stable'; const LABELS: Record = { added: 'Added in', changed: 'Changed in', deprecated: 'Deprecated in', + stable: 'Stable in', }; interface VersionBadgeProps {