Skip to main content
Version: v4

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.

Extensions​

Added in: v4.2.0

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 (Experimental)​

Added in: v4.6.0 (experimental)

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 reference for complete documentation.

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​