|
1 | 1 | # Applications
|
2 | 2 |
|
3 |
| -## Overview of HarperDB Applications |
4 |
| - |
5 | 3 | Harper is more than a database, it's a distributed clustering platform allowing you to package your schema, endpoints and application logic and deploy them to an entire fleet of Harper instances optimized for on-the-edge scalable data delivery.
|
6 | 4 |
|
7 |
| -In this guide, we are going to explore the evermore extensible architecture that Harper provides by building a Harper component, a fundamental building-block of the Harper ecosystem. |
| 5 | +In this guide, we are going to explore the evermore extensible architecture that Harper provides by building a Harper application, a fundamental building-block of the Harper ecosystem. |
8 | 6 |
|
9 | 7 | When working through this guide, we recommend you use the [Harper Application Template](https://github.com/HarperDB/application-template) repo as a reference.
|
10 | 8 |
|
11 |
| -## Understanding the Component Application Architecture |
| 9 | +Before we get started, let's clarify some terminology that is used throughout the documentation. |
| 10 | + |
| 11 | +**Components** are the high-level concept for modules that extend the Harper core platform adding additional functionality. The application you will build here is a component. In addition to applications, components also encompass extensions. |
| 12 | + |
| 13 | +> We are actively working to disambiguate the terminology. When you see "component", such as in the Operations API or CLI, it generally refers to an application. We will do our best to clarify exactly which classification of a component whenever possible. |
| 14 | +
|
| 15 | +**Applications** are best defined as the implementation of a specific user-facing feature or functionality. Applications are built on top of extensions and can be thought of as the end product that users interact with. For example, a Next.js application that serves a web interface or an Apollo GraphQL server that provides a GraphQL API are both applications. |
| 16 | + |
| 17 | +**Extensions** are the building blocks of the Harper component system. Applications depend on extensions to provide the functionality the application is implementing. For example, the built-in `graphqlSchema` extension enables applications to define their databases and tables using GraphQL schemas. Furthermore, the `@harperdb/nextjs` and `@harperdb/apollo` extensions are the building blocks that provide support for building Next.js and Apollo applications. |
| 18 | + |
| 19 | +All together, the support for implementing a feature is the extension, and the actual implementation of the feature is the application. |
12 | 20 |
|
13 |
| -Harper provides several types of components. Any package that is added to Harper is called a "component", and components are generally categorized as either "applications", which deliver a set of endpoints for users, or "extensions", which are building blocks for features like authentication, additional protocols, and connectors that can be used by other components. Components can be added to the `hdb/components` directory and will be loaded by Harper when it starts. Components that are remotely deployed to Harper (through the studio or the operation API) are installed into the `hdb/node_modules` directory. Using `harperdb run .` or `harperdb dev .` allows us to specifically load a certain application in addition to any that have been manually added to `hdb/components` or installed (in `hdb/node_modules`). |
| 21 | +Extensions can also depend on other extensions. For example, the [`@harperdb/apollo`](https://github.com/HarperDB/apollo) extension depends on the built-in `graphqlSchema` extension to create a cache table for Apollo queries. Applications can then use the `@harperdb/apollo` extension to implement an Apollo GraphQL backend server. |
14 | 22 |
|
15 | 23 | ```mermaid
|
16 |
| -flowchart LR |
17 |
| - Client(Client)-->Endpoints |
18 |
| - Client(Client)-->HTTP |
19 |
| - Client(Client)-->Extensions |
20 |
| - subgraph Harper |
| 24 | +flowchart TD |
| 25 | + subgraph Applications |
21 | 26 | direction TB
|
22 |
| - Applications(Applications)-- "Schemas" --> Tables[(Tables)] |
23 |
| - Applications-->Endpoints[/Custom Endpoints/] |
24 |
| - Applications-->Extensions |
25 |
| - Endpoints-->Tables |
26 |
| - HTTP[/REST/HTTP/]-->Tables |
27 |
| - Extensions[/Extensions/]-->Tables |
| 27 | + NextJSApp["Next.js App"] |
| 28 | + ApolloApp["Apollo App"] |
| 29 | + CustomResource["Custom Resource"] |
| 30 | + end |
| 31 | +
|
| 32 | + subgraph Extensions |
| 33 | + direction TB |
| 34 | + subgraph Custom |
| 35 | + NextjsExt["@harperdb/nextjs"] |
| 36 | + ApolloExt["@harperdb/apollo"] |
| 37 | + end |
| 38 | + subgraph Built-In |
| 39 | + GraphqlSchema["graphqlSchema"] |
| 40 | + JsResource["jsResource"] |
| 41 | + Rest["rest"] |
28 | 42 | end
|
| 43 | + end |
| 44 | +
|
| 45 | + subgraph Core |
| 46 | + direction TB |
| 47 | + Database["database"] |
| 48 | + FileSystem["file-system"] |
| 49 | + Networking["networking"] |
| 50 | + end |
| 51 | +
|
| 52 | + NextJSApp --> NextjsExt |
| 53 | + ApolloApp --> ApolloExt |
| 54 | + CustomResource --> JsResource & GraphqlSchema & Rest |
| 55 | +
|
| 56 | + NextjsExt --> Networking |
| 57 | + NextjsExt --> FileSystem |
| 58 | + ApolloExt --> GraphqlSchema |
| 59 | + ApolloExt --> Networking |
| 60 | +
|
| 61 | + GraphqlSchema --> Database |
| 62 | + JsResource --> Database |
| 63 | + Rest --> Networking |
| 64 | +
|
29 | 65 | ```
|
30 | 66 |
|
| 67 | +> As of Harper v4.6, a new, **experimental** component system has been introduced called **plugins**. Plugins are a **new iteration of the existing extension system**. They are simultaneously a simplification and an extensibility upgrade. Instead of defining multiple methods (`start` vs `startOnMainThread`, `handleFile` vs `setupFile`, `handleDirectory` vs `setupDirectory`), plugins only have to define a single `handleComponent` method. Plugins are **experimental**, and complete documentation is available on the [plugin API](../../technical-details/reference/components/plugins.md) page. In time we plan to deprecate the concept of extensions in favor of plugins, but for now, both are supported. |
| 68 | +
|
| 69 | +Beyond applications and extensions, components are further classified as built-in or custom. **Built-in** components are included with Harper by default and can be directly referenced by their name. The `graphqlSchema`, `rest`, and `jsResource` extensions used in the previous application example are all examples of built-in extensions. **Custom** components must use external references, generally npm or GitHub packages, and are often included as dependencies within the `package.json` of the component. |
| 70 | + |
| 71 | +> Harper maintains a number of custom components that are available on `npm` and `GitHub`, such as the [`@harperdb/nextjs`](https://github.com/HarperDB/nextjs) extension or the [`@harperdb/status-check`](https://github.com/HarperDB/status-check) application. |
| 72 | +
|
| 73 | +Harper does not currently include any built-in applications, making "custom applications" a bit redundant. Generally, we just say "application". However, there is a multitude of both built-in and custom extensions, and so the documentation refers to them as such. A complete list of built-in extensions is available in the [Built-In Extensions](../../technical-details/reference/components/built-in.md) documentation page, and the list of custom extensions and applications is available below. |
| 74 | + |
| 75 | +This guide is going to walk you through building a basic Harper application using a set of built-in extensions. |
| 76 | + |
| 77 | +> The Technical Details section of the documentation contains a [complete reference for all aspects of components](../../technical-details/reference/components), applications, extensions, and more. |
| 78 | +
|
31 | 79 | ## Custom Functionality with JavaScript
|
32 | 80 |
|
33 | 81 | [The getting started guide](../../getting-started/first-harper-app.md) covers how to build an application entirely through schema configuration. However, if your application requires more custom functionality, you will probably want to employ your own JavaScript modules to implement more specific features and interactions. This gives you tremendous flexibility and control over how data is accessed and modified in Harper. Let's take a look at how we can use JavaScript to extend and define "resources" for custom functionality. Let's add a property to the dog records when they are returned, that includes their age in human years. In Harper, data is accessed through our [Resource API](../../technical-details/reference/resource.md), a standard interface to access data sources, tables, and make them available to endpoints. Database tables are `Resource` classes, and so extending the function of a table is as simple as extending their class.
|
@@ -163,16 +211,7 @@ Harper provides a powerful JavaScript API with significant capabilities that go
|
163 | 211 |
|
164 | 212 | ## Configuring Applications/Components
|
165 | 213 |
|
166 |
| -Every application or component can define their own configuration in a `config.yaml`. If you are using the application template, you will have a [default configuration in this config file](https://github.com/HarperDB/application-template/blob/main/config.yaml) (which is default configuration if no config file is provided). Within the config file, you can configure how different files and resources are loaded and handled. The default configuration file itself is documented with directions. Each entry can specify any `files` that the loader will handle, and can also optionally specify what, if any, URL `path`s it will handle. A path of `/` means that the root URLs are handled by the loader, and a path of `.` indicates that the URLs that start with this application's name are handled. |
167 |
| -
|
168 |
| -This config file allows you define a location for static files, as well (that are directly delivered as-is for incoming HTTP requests). |
169 |
| -
|
170 |
| -Each configuration entry can have the following properties, in addition to properties that may be specific to the individual component: |
171 |
| -
|
172 |
| -* `files`: This specifies the set of files that should be handled the component. This is a glob pattern, so a set of files can be specified like "directory/\*\*". |
173 |
| -* `path`: This is the URL path that is handled by this component. |
174 |
| -* `root`: This specifies the root directory for mapping file paths to the URLs. For example, if you want all the files in `web/**` to be available in the root URL path via the static handler, you could specify a root of `web`, to indicate that the web directory maps to the root URL path. |
175 |
| -* `package`: This is used to specify that this component is a third party package, and can be loaded from the specified package reference (which can be an NPM package, Github reference, URL, etc.). |
| 214 | +For complete information of configuring applications, refer to the [Component Configuration](../../technical-details/reference/components/configuration.md) reference page. |
176 | 215 |
|
177 | 216 | ## Define Fastify Routes
|
178 | 217 |
|
|
0 commit comments