Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/deriegle/express-hotwire
Express tooling for working with Hotwire (HTML over the wire) https://hotwire.dev
https://github.com/deriegle/express-hotwire
express express-middleware expressjs hotwire nodejs
Last synced: 9 days ago
JSON representation
Express tooling for working with Hotwire (HTML over the wire) https://hotwire.dev
- Host: GitHub
- URL: https://github.com/deriegle/express-hotwire
- Owner: deriegle
- License: mit
- Created: 2020-12-26T01:53:06.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-29T20:42:24.000Z (10 days ago)
- Last Synced: 2024-10-29T22:51:00.684Z (10 days ago)
- Topics: express, express-middleware, expressjs, hotwire, nodejs
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/express-hotwire
- Size: 434 KB
- Stars: 42
- Watchers: 2
- Forks: 4
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Express library for working with Hotwire (HTML over the wire)
This project was built to provide tooling for working with the new `@hotwired/turbo` package built by Basecamp for their **NEW MAGIC** used with hey.com. I wanted to try building similar tooling in express as an example for how this can implemented in other languages, but also to help me learn how it works under the hood.
## Using the library
1. Add the `express-hotwire` package to your project
**Using npm**
```bash
npm install express-hotwire
```
**Using yarn**
```bash
yarn add express-hotwire
```
2. Use the middleware with your app
```js
const express = require('express');
const expressHotwire = require('express-hotwire');
const app = express();
app.use(expressHotwire());
```
3. Render your turbo stream responses using the res.turboStream object.
```js
app.post('/messages', async (req, res) => {
const { content } = req.fields;
// create message and save in database/memory/etc
const message = create(content);
// Make sure the first argument matches the HTML element id that you want to append a child to
await res.turboStream.append('messages', {
partial: 'messages/show', // This should be inside your views directory as views/messages/show.ejs
locals: {
// Add any variables needed to render the partial
message,
},
});
});
```
## Turbo Stream Messages and Actions
We provide helpful methods for all the actions listed in the [hotwire.dev docs](https://turbo.hotwire.dev/handbook/streams).
```js
// The contents of the partial will be appended to the element with DOM ID "messages".
res.turboStream.append('messages', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
});
// The contents of the partial will be prepended to the element with the DOM ID "messages".
res.turboStream.prepend('messages', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
});
// The contents of the partial will replace the existing element with the DOM ID "message_1".
res.turboStream.replace('message_1', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
});
// The contents of the partial will update the element with DOM ID "unread_count".
res.turboStream.update('unread_count', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
});
// The element with DOM ID "message_1" will be removed.
res.turboStream.remove('message_1');
```
## Sending Multiple TurboStreams
Sometimes you want to return multiple turbo streams from a request handler.
You can use the `res.turboStream.multiple` function to do that.
You have access to all the same `turboStream` methods in the callback as defined above.
**Note: You cannot call `turboStream.multiple` from within the callback. We don't support nested calls to `.multiple`**
```js
await res.turboStream.multiple((turboStream) => [
turboStream.append('messages', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
}),
turboStream.prepend('messages', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
}),
turboStream.replace('message_1', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
}),
turboStream.update('unread_count', {
partial: 'messages/show',
locals: {
message: { id: 1, content: 'Hi' },
},
}),
turboStream.remove('message_1'),
]);
```