diff --git a/README.md b/README.md index 8306d05..1e4667a 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,9 @@ NeverChange is a database solution for web applications using SQLite WASM and OP - [Installation](#installation) - [Supported Browsers](#supported-browsers) -- [You want to host on GitHub Pages and Netlify](#you-want-to-host-on-github-pages-and-netlify) +- [About Application Deployment](#about-application-deployment) + - [Netlify (Recommendation)](#netlify-recommendation) + - [GitHub Pages](#github-pages) - [Requirements](#requirements) - [Usage](#usage) - [Basic](#basic) @@ -36,19 +38,36 @@ npm install neverchange ## Supported Browsers -This project currently supports and is tested on `Google Chrome` only. -We use `Playwright` for our end-to-end (E2E) tests, which are configured to run exclusively on `Chrome`. - -All tests are tested only through Playwright. +All end-to-end tests are conducted with Playwright in Chrome, Edge, Chromium, and Firefox. * Google Chrome * Microsoft Edge * Firefox -* ~~Safari~~ (https://github.com/shinshin86/neverchange/issues/6) +* Safari + * (However, there are restrictions. See [About Application Deployment](#about-application-deployment) for more information.) + +## About Application Deployment +Our recommendation is to deploy with Netlify for better compatibility. See below for Netlify and GitHub Pages deployment instructions. + + +A full deployment guide is available in the [Deployment Documentation](docs/deployment.md), including specific configuration examples. + +### Netlify (Recommendation) + +Netlify is recommended for deploying apps with persistent data on the web front end using NeverChange. -## You want to host on GitHub Pages and Netlify -If you want to host on GitHub Pages and Netlify, you will need [coi-serviceworker.js](https://github.com/gzuidhof/coi-serviceworker). -Also, Safari does not function properly in this case. Refer to the following issue for more details. +The following statement in the `_headers` file can be used for this purpose. + +``` +/* + Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp +``` + +### GitHub Pages +If you want to host on GitHub Pages, you will need [coi-serviceworker.js](https://github.com/gzuidhof/coi-serviceworker). + +But, Safari does not function properly in this case. Refer to the following issue for more details. https://github.com/shinshin86/neverchange/issues/6 example: @@ -58,7 +77,7 @@ example: NeverChange Example - + @@ -68,7 +87,7 @@ example: ``` -A more detailed deployment guide can be found in the [Deployment Documentation](docs/deployment.md). +A full deployment guide is available in the [Deployment Documentation](docs/deployment.md), including specific configuration examples. ## Requirements @@ -79,7 +98,8 @@ A more detailed deployment guide can be found in the [Deployment Documentation]( ![Usage image](./images/Usage.jpg) -Here’s how to use NeverChange. +Here’s how to use NeverChange with some practical examples. + If you’re interested in writing SQL efficiently with NeverChange, you may also want to check out [sqlc-gen-typescript-for-neverchange](https://github.com/shinshin86/sqlc-gen-typescript-for-neverchange), which generates TypeScript code using [sqlc](https://github.com/sqlc-dev/sqlc). ### Basic @@ -239,7 +259,7 @@ const blobData = convertToUint8Array(row.blobColumn); ### CSV Export and Import -NeverChangeDB also supports CSV export and import functionality, allowing you to easily work with CSV files in your database. +NeverChangeDB also supports CSV export and import functionality, which is useful for integrating with spreadsheet applications and external data sources. #### CSV Export diff --git a/docs/deployment.md b/docs/deployment.md index d39086a..472e236 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,64 +1,44 @@ -# Deployment Guide (GitHub Pages and Netlify) +# Deployment Documentation This document provides detailed instructions for deploying NeverChange on GitHub Pages and Netlify. Follow the steps below to set up your deployment. ## Table of Contents - [Prerequisites](#prerequisites) -- [When using Vite on GitHub Pages](#when-using-vite-on-github-pages) -- [When using Vite on Netlify](#when-using-vite-on-netlify) +- [Netlify (Recommendation)](#netlify-recommendation) + - [When using Vite on Netlify](#when-using-vite-on-netlify) +- [GitHub Pages](#github-pages) + - [When using Vite on GitHub Pages](#when-using-vite-on-github-pages) ## Prerequisites -Both GitHub Pages and Netlify require the use of [coi-serviceworker.js](https://github.com/gzuidhof/coi-serviceworker). +To enable `OPFS` and `SharedArrayBuffer` (which is used internally by `SQLite Wasm`), you need to add two specific headers to your site’s server configuration: -When using GitHub Pages, OPFS is unavailable because you cannot set the `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers. +* Cross-Origin-Opener-Policy: same-origin +* Cross-Origin-Embedder-Policy: require-corp -The `coi-serviceworker` helps work around this limitation. +These headers allow your site to use certain advanced features necessary for NeverChange to work properly. -However, this service worker mechanism does not function correctly in Safari, making Safari incompatible with these environments. +## Netlify (Recommendation) +Netlify is recommended for easy setup and compatibility with Safari on iPhone. -You can load and use it in HTML as shown below: +Place the `_headers` file in the root directory of your deployment destination, with the following configuration: -```html - - - - NeverChange Example - - - - -
- - - +``` +/* + Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp ``` -## When using Vite on GitHub Pages -If you are building a site with Vite + React on GitHub Pages, use the following configuration to ensure compatibility with OPFS. +### When using Vite on Netlify + +Also, if you use Vite during development, remember to put the following in `vite.config.{ts|js}`. ```typescript -import { defineConfig, Plugin } from 'vite'; +import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; -// This htmlPlugin configuration is tailored for GitHub Pages. It automatically injects the coi-serviceworker.js script into the HTML during build time. -// It's useful for ensuring that the necessary service worker is included without manually editing the HTML file. -// This helps avoid cross-origin issues and enables the COOP and COEP headers required for OPFS. -const htmlPlugin = (): Plugin => { - return { - name: 'html-transform', - transformIndexHtml(html: string) { - return html.replace( - '', - `\n `, - ); - }, - }; -}; - export default defineConfig({ - base: '/your-project-name/', - plugins: [react(), htmlPlugin()], + plugins: [react()], server: { headers: { 'Cross-Origin-Opener-Policy': 'same-origin', @@ -71,20 +51,37 @@ export default defineConfig({ }); ``` +## GitHub Pages +If you use GitHub Pages, you cannot use OPFS because you cannot set the `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` headers. -## When using Vite on Netlify -If you are building a site with Vite + React on Netlify, use the following configuration to ensure compatibility with OPFS. +Therefore, you must use [coi-serviceworker.js](https://github.com/gzuidhof/coi-serviceworker) on GitHub Pages, but note that it doesn’t fully support Safari. + +You can load and use it in HTML as shown below. + +```html + + + + NeverChange Example + + + + +
+ + + +``` -This setup is similar to the GitHub Pages method, but on Netlify, you don’t need to specify the `base: '/your-project-name/'` option, as Netlify’s URLs are typically in the format `http(s)://.netlify.app/`, and a base path isn’t required. +### When using Vite on GitHub Pages -Note that `htmlPlugin` also differs slightly for the same reason, so please take note of this difference. +If you are building your app using Vite for GitHub Pages, you may want to prepare a configuration file (`vite.config.{ts|js}`) similar to this: ```typescript import { defineConfig, Plugin } from 'vite'; import react from '@vitejs/plugin-react'; -// This htmlPlugin configuration is tailored for Netlify. It automatically injects the coi-serviceworker.js script into the HTML during build time. -// It's useful for ensuring that the necessary service worker is included without manually editing the HTML file. +// This htmlPlugin automatically injects the coi-serviceworker.js script into the HTML . // This helps avoid cross-origin issues and enables the COOP and COEP headers required for OPFS. const htmlPlugin = (): Plugin => { return { @@ -92,13 +89,14 @@ const htmlPlugin = (): Plugin => { transformIndexHtml(html: string) { return html.replace( '', - `\n `, + `\n `, ); }, }; }; export default defineConfig({ + base: '/your-project-name/', plugins: [react(), htmlPlugin()], server: { headers: {