Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vilicvane/backpage
Naive static HTML streaming based on React for Node.js CLI applications.
https://github.com/vilicvane/backpage
cli gui html nodejs react
Last synced: 20 days ago
JSON representation
Naive static HTML streaming based on React for Node.js CLI applications.
- Host: GitHub
- URL: https://github.com/vilicvane/backpage
- Owner: vilicvane
- License: mit
- Created: 2024-01-12T21:42:32.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2024-05-13T11:02:34.000Z (7 months ago)
- Last Synced: 2024-11-28T00:34:14.998Z (26 days ago)
- Topics: cli, gui, html, nodejs, react
- Language: TypeScript
- Homepage: https://backpage.cloud
- Size: 264 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/backpage)
[](./package.json)
[](./LICENSE)
[](https://discord.gg/wEVn2qcf8h)
# BackPage
Naive static HTML streaming based on React for Node.js CLI applications.
## How does it work?
BackPage renders your React application to HTML and streams updates (**static** HTML snapshots) to your browser.
It is designed for really simple GUI as a complementary to text logs, so **advanced user interaction is neither supported nor its goal.**
## Features
- Stream static HTML from React rendering.
- Send notification to browser.
- Simple user interaction with HTML form.
- Simple webhook usages with `/action/[action-name]` and `/notify` endpoints.
- Public URL via [backpage.cloud](https://backpage.cloud).
## Table of Contents
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Form-based Interaction](#form-based-interaction)
- [Events](#events)
- [click](#click)
- [input](#input)
- [Browser Notification](#browser-notification)
- [Action](#action)
- [BackPage Cloud](#backpage-cloud)
- [Examples](#examples)
- [Built-in Components](#built-in-components)
- [Form](#form)
- [ActionButton](#actionbutton)
- [Title](#title)
- [Style](#style)
- [Console](#console)
## Installation
```bash
npm install react backpage
```
## Basic Usage
**main.tsx**
```tsx
import {BackPage} from 'backpage';
import React from 'react';
import {App} from './app.js';
const page = new BackPage();
page.render();
// Print page information including URL.
page.guide();
```
**app.tsx**
```tsx
import React, {useState, useEffect} from 'react';
export const App = () => {
const [count, setCount] = useState(0);
useEffect(() => {
const timer = setInterval(
setCount(count => count + 1),
1000,
);
return () => clearInterval(timer);
}, []);
return
Count: {count};
};
```
## Form-based Interaction
See [Form](#form) and [ActionButton](#actionbutton) for simple usage.
## Events
BackPage can proxy explicitly specified events that bubble to `document` from the browser to your Node.js React application.
```tsx
const page = new BackPage({
events: ['click'],
});
page.render(
{
console.info('This will work.');
}}
>
Click me!
,
);
```
> Events are proxied asynchronously, and just for the purpose of triggering actions in your Node.js application.
> Not all events bubble, please checkout relevant documents for more information.
### click
Properties:
- `altKey`
- `ctrlKey`
- `metaKey`
- `shiftKey`
### input
Effects:
- Sets `event.target.value` to the value of the input element.
## Browser Notification
A notification can be sent to the browser using either `page.notify()` or `/notify` endpoint.
To send notification to the browser using `page.notify()`:
```ts
page.notify('Hello BackPage!');
page.notify({
title: 'Hello BackPage!',
body: 'This is a notification from BackPage.',
});
```
You can also setup a fallback for notifications not getting **clicked** within the timeout:
```ts
const page = new BackPage({
notify: {
// timeout: 30_000,
fallback: notification => {
// Handle the notification manually.
// Optionally return a webhook URL or request options to initiate an HTTP
// request.
return 'https://some.webhook/';
},
},
});
page.notify({
title: 'Hello BackPage!',
body: 'Click me or your webhook will get fired!',
});
```
To send notification to the browser using `/notify` endpoint:
```ts
await fetch('http://localhost:12368/notify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Hello BackPage!',
body: 'This is a notification from BackPage.',
}),
});
```
> A `timeout` field can also be specified (a number or `false`) to override the default value.
## Action
A simple webhook can be setup with `/action/[action-name]` endpoint.
```ts
page.registerAction('hello', data => {
console.info('Hello', data);
});
```
To trigger this action:
```ts
await fetch('http://localhost:12368/action/hello', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'BackPage',
}),
});
```
This uses the same mechanism as the `Form` action, so you may want to avoid using the same action name (if you explicitly specify one for `Form`).
## BackPage Cloud
By specifying a UUID as token, you can get a public URL from [backpage.cloud](https://backpage.cloud):
```ts
import {BackPage, getPersistentToken} from 'backpage';
const page = new BackPage({
// You can also use any random UUID for temporary page.
token: getPersistentToken(),
// Different pages can be setup using the same token with different names.
// name: 'project-name',
});
page.guide();
```
You can also create a temporary front only page for web notifications using .
> **Note:** [backpage.cloud](https://backpage.cloud) may introduce value-added services for significant network traffic to cover the expense in the future.
## Examples
Check out [src/examples](./src/examples).
## Built-in Components
### Form
A `Form` is based on HTML `form` element and has similar usage, except that `action` is proxied backed by `POST` requests and accepts callback with the form data object as its parameter.
```tsx
const action = data => console.info(data);
page.render(
Submit
,
);
```
### ActionButton
In many cases, only the button is relevant for an action. `ActionButton` wraps a button within a `Form` for those cases:
```tsx
const action = () => console.info('Launch!');
page.render(Launch);
```
You can also put multiple `ActionButton`s in an explicit `Form` to share the form inputs:
```tsx
const actionA = data => console.info('action-a', data);
const actionB = data => console.info('action-b', data);
page.render(
Action A
Action B
,
);
```
### Title
Sets `document.title` of the page.
```tsx
page.render(
<>
Awesome Page
Hello BackPage!
>,
);
```
> You can also specify `title` in `BackPage` options if it not dynamic.
### Style
Adds a `style` element to the page with content loaded from `src` (local path).
```tsx
const App = () => (
<>
Hello BackPage!
>
);
```
> You can directly use `` for CSS links.
### Console
Intercepts console outputs using [patch-console](https://www.npmjs.com/package/patch-console).
```tsx
const App = () => (
<>
Logs
>
);
```
## License
MIT License.