Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs for Safari #9

Merged
merged 1 commit into from
Nov 6, 2024
Merged

Docs for Safari #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 33 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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:
Expand All @@ -58,7 +77,7 @@ example:
<html>
<head>
<title>NeverChange Example</title>
<!-- If you want to host on GitHub Pages and Netlify, you will need coi-serviceworker.js -->
<!-- If you want to host on GitHub, you will need coi-serviceworker.js -->
<script src="/coi-serviceworker.js"></script>
</head>
<body>
Expand All @@ -68,7 +87,7 @@ example:
</html>
```

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

Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down
94 changes: 46 additions & 48 deletions docs/deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<!DOCTYPE html>
<html>
<head>
<title>NeverChange Example</title>
<!-- coi-serviceworker.js is required for GitHub Pages or Netlify hosting -->
<script src="/coi-serviceworker.js"></script>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
```
/*
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 <head> 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(
'</title>',
`</title>\n <script src="/your-project-name/coi-serviceworker.js"></script>`,
);
},
};
};

export default defineConfig({
base: '/your-project-name/',
plugins: [react(), htmlPlugin()],
plugins: [react()],
server: {
headers: {
'Cross-Origin-Opener-Policy': 'same-origin',
Expand All @@ -71,34 +51,52 @@ 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
<!DOCTYPE html>
<html>
<head>
<title>NeverChange Example</title>
<!-- coi-serviceworker.js is required for GitHub Pages -->
<script src="/your-project-name/coi-serviceworker.js"></script>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
```

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)://<project-name>.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 <head> 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 <head>.
// 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(
'</title>',
`</title>\n <script src="/coi-serviceworker.js"></script>`,
`</title>\n <script src="/your-project-name/coi-serviceworker.js"></script>`,
);
},
};
};

export default defineConfig({
base: '/your-project-name/',
plugins: [react(), htmlPlugin()],
server: {
headers: {
Expand Down
Loading