https://github.com/alignable/bifrost
Bridge to React
https://github.com/alignable/bifrost
Last synced: about 1 year ago
JSON representation
Bridge to React
- Host: GitHub
- URL: https://github.com/alignable/bifrost
- Owner: Alignable
- Created: 2023-05-01T21:45:03.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2024-09-16T18:02:59.000Z (almost 2 years ago)
- Last Synced: 2024-09-16T22:14:29.108Z (almost 2 years ago)
- Language: TypeScript
- Size: 654 KB
- Stars: 3
- Watchers: 9
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
bifrost is the framework for incremental migration from Rails/Turbolinks to Vite-powered React SSR.
# How does it work?
1. Vike tries to handle request
2. If it cannot, proxy to Rails
3. If Rails returns layout, wrap in layout
4. Else just return as-is
## Breaking changes moving from turbolinks to bifrost:
- turbolinks-permanent is gone
- request:start and request:end events removed
- Some discrepency in event data and exactly when they fire
## Getting Started
### Installation
Install and setup [Vike](https://vike.dev/) (don't use vike-react)
Install a Fastify server
Install `@alignable/bifrost` and `@alignable/bifrost-fastify`
In fastify, register viteProxyPlugin
Create your default config `renderer/+config.ts` with `extends [BifrostConfig]` and default `proxyMode: false`, which lets you build Vike-rendered pages.
### Proxy modes
The "wrapped" proxy mode is the main point of Bifrost. The backend proxies your request to Rails and wraps the result in a React layout component. It copies over any attributes on the `body` tag, and inserts tags inside `head`, including running any scripts.
When the user clicks a link, it will check your Vike routing rules. If the route has `proxyMode: wrapped`, it will make a request to Rails and do all of the above, this time on the client. If the link is to a Vike page with `proxyMode: false`, it will render that page instead.
The "passthru" proxy mode is an option of incremental migration. Passthru routes simply render whatever Rails returns. This lets you start building Vike/Bifrost pages without committing to the full wrapped experience.
### Setting up Wrapped Proxy
1. In Rails check for a `x-vite-proxy` (name configurable) header and skip rendering the layout, so Bifrost can render the layout, enabling seamless page transitions. Also return which layout the page needs + any layout config/props via another header.
2. In Bifrost, setup a page with `proxyMode: wrapped` and configure the following:
1. `getLayout` is a function to pull layout name and properties from the headers returned by Rails.
2. `layoutMap` maps layout names to layout components
3. `proxyHeaders` adds the `x-vite-proxy` (or other named header) to signal Rails you're coming from Bifrost.
3. Move your navbar/layouts to be render-able via Bifrost
4. (Optional) Setup your load balancer toggle traffic to Bifrost/Rails based on the `x-vite-proxy` header. This enables the frontend to hit Rails directly on client-side navigation, reducing overhead.