Skip to main content
Version: v5

Components

Components are the high-level concept for modules that extend the Harper core platform with additional functionality. Components encapsulate both applications and extensions.

Harper is actively working to disambiguate component terminology. When you see "component" in the Operations API or CLI, it generally refers to an application. Documentation does its best to clarify which classification of component is meant wherever possible.

Concepts​

Applications​

Added in: v4.2.0

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.

Plugins​

Stable in: v5.0.0 Added in: v4.6.0

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 can also depend on other plugins. For example, @harperfast/nextjs depends on the built-in graphqlSchema to create caching tables.

Extensions​

Deprecated in: v5.0.0 Added in: v4.2.0

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​

Built-in components are included with Harper by default and referenced directly by name. Examples include graphqlSchema, rest, jsResource, static, and loadEnv.

Custom components use external references—npm packages, GitHub repositories, or local directories—and are typically included as package.json dependencies.

Harper does not currently include built-in applications. All applications are custom.

Architecture​

The relationship between applications, extensions, and Harper core:

Applications
 ├── Next.js App        → @harperdb/nextjs extension
 ├── Apollo App         → @harperdb/apollo extension
 └── Custom Resource    → jsResource + graphqlSchema + rest extensions

Extensions
 ├── Custom: @harperdb/nextjs, @harperdb/apollo, @harperdb/astro
 └── Built-In: graphqlSchema, jsResource, rest, static, loadEnv, ...

Core
 └── database, file-system, networking

Configuration​

Harper components are configured with a config.yaml file in the root of the component module directory. This file is how a component configures other components it depends on. Each entry starts with a component name, with configuration values indented below:

componentName:
  option-1: value
  option-2: value

Default Configuration​

Components without a config.yaml get this default configuration automatically:

rest: true
graphqlSchema:
  files: '*.graphql'
roles:
  files: 'roles.yaml'
jsResource:
  files: 'resources.js'
fastifyRoutes:
  files: 'routes/*.js'
  urlPath: '.'
static:
  files: 'web/**'

If a config.yaml is provided, it replaces the default config entirely (no merging).

Custom Component Configuration​

Any custom component must be configured with a package option for Harper to load it. The component name must match a package.json dependency:

{
	"dependencies": {
		"@harperdb/nextjs": "1.0.0"
	}
}
'@harperdb/nextjs':
  package: '@harperdb/nextjs'
  files: './'

The package value supports any valid npm dependency specifier: npm packages, GitHub repos, tarballs, local paths, and URLs. This is because Harper generates a package.json from component configurations and uses npm install to resolve them.

Extension and Plugin Configuration​

Extensions require an extensionModule option pointing to the extension source. Plugins require a pluginModule option. See Extension API and Plugin API for details.

Built-In Extensions Reference​

NameDescription
dataLoaderLoad data from JSON/YAML files into Harper tables
fastifyRoutesDefine custom endpoints with Fastify
graphqlEnable GraphQL querying (experimental)
graphqlSchemaDefine table schemas with GraphQL syntax
jsResourceDefine custom JavaScript-based resources
loadEnvLoad environment variables from .env files
restEnable automatic REST endpoint generation
rolesDefine role-based access control from YAML files
staticServe static files via HTTP

Known Custom Components​

Applications​

Extensions​

Component Status Monitoring​

Added in: v4.7.0

Harper collects status from each component at load time and tracks any registered status change notifications. This provides visibility into the health and state of running components.

Evolution History​

  • v4.1.0 — Custom functions with worker threads (predecessor to components)
  • v4.2.0 — Component architecture introduced; Resource API, REST interface, MQTT, WebSockets, SSE, configurable schemas
  • v4.3.0 — Component configuration improvements
  • v4.6.0 — New extension API with dynamic reloading; Plugin API introduced (experimental)
  • v4.7.0 — Component status monitoring; further plugin API improvements

See Also​