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

Use @sveltejs/adapter-static on GitHub Pages #5845

Closed
wants to merge 11 commits into from
Closed

Use @sveltejs/adapter-static on GitHub Pages #5845

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5f85f56
Detected environment: GitHub Pages. Using @sveltejs/adapter-static
NatoBoram Aug 7, 2022
1e998b8
Add a changeset file
NatoBoram Aug 7, 2022
dda286b
Add @sveltejs/adapter-static to @sveltejs/adapter-auto's dependencies
NatoBoram Aug 7, 2022
afb15ea
Add default config for adapter-static on GH Pages
NatoBoram Aug 7, 2022
a5a3986
Set GITHUB_ACTIONS: undefined for testing
NatoBoram Aug 7, 2022
beefcb2
Add a .nojekyll when building for GitHub Pages
NatoBoram Aug 7, 2022
d0e91ca
📝 Add doc on GitHub Pages
NatoBoram Aug 10, 2022
2bb0550
Use $GITHUB_PAGES
NatoBoram Aug 16, 2022
ca7a09d
New changeset since no longer editing create-svelte
NatoBoram Aug 16, 2022
bae8090
📝 More instructions on using GitHub Pages
NatoBoram Sep 4, 2022
94d6594
🎨 Convert indentation to spaces
NatoBoram Sep 4, 2022
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
6 changes: 6 additions & 0 deletions .changeset/nasty-adults-eat.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@sveltejs/adapter-auto': patch
'@sveltejs/adapter-static': patch
---

Use adapter-static with GitHub Pages
62 changes: 62 additions & 0 deletions documentation/docs/10-adapters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ You can deploy to the following platforms with the default adapter, `adapter-aut
- [Cloudflare Pages](https://developers.cloudflare.com/pages/) via [`adapter-cloudflare`](https://github.com/sveltejs/kit/tree/master/packages/adapter-cloudflare)
- [Netlify](https://netlify.com) via [`adapter-netlify`](https://github.com/sveltejs/kit/tree/master/packages/adapter-netlify)
- [Vercel](https://vercel.com) via [`adapter-vercel`](https://github.com/sveltejs/kit/tree/master/packages/adapter-vercel)
- [GitHub Pages](https://pages.github.com) via [`adapter-static`](https://github.com/sveltejs/kit/tree/master/packages/adapter-static)

#### Node.js

Expand Down Expand Up @@ -56,6 +57,67 @@ You can also use `adapter-static` to generate single-page apps (SPAs) by specify

> You must ensure [`trailingSlash`](configuration#trailingslash) is set appropriately for your environment. If your host does not render `/a.html` upon receiving a request for `/a` then you will need to set `trailingSlash: 'always'` to create `/a/index.html` instead.

#### GitHub Pages
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this section should really go in the adapter-static README (there's already a GitHub Pages section). maybe it should be an npm example instead of pnpm? many more people use it. or we could have something like

packages/adapter-static/examples/github-pages-npm/build.yaml
packages/adapter-static/examples/github-pages-pnpm/build.yaml


SvelteKit can be automatically configured for deployment on GitHub Pages by using the [`actions/configure-pages`](https://github.com/actions/configure-pages) GitHub Action before building it. This action will set `GITHUB_PAGES=true` and replace `kit.paths.base` in `svelte.config.js` by the correct path for your GitHub repository.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the automatic kit.paths.base replacement makes me super nervous. hacks like this are guaranteed to break for a percentage of users, and it's hard to test locally. it should really be an environment variable that you add to your config — does something like this exist?

// svelte.config.js
export default {
  kit: {
    adapter: adapter(),
    paths: { base: process.env.GITHUB_PAGES_PATH ?? '' }
  }
};

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear, this is an optional feature of actions/configure-pages enabled with this setting. I think the reason they decided to go with config replacement is so that their starter-workflows would require zero config changes to work. I'm not entirely sure though...

In conversation with them about environment variables, they were also against providing environment variables for all the necessary site info (pages path, site origin, etc.). That's not to say the info isn't available. In a workflow, you could manually forward the data from their workflow step as outputs into environment variables in the build step.

In the adapter-static README, I think we could provide two workflows, with one using automatic replacement (warning users of potential issues) and the other using our own environment variables. The reason for this is that I don't think the automatic replacement version will go away. After this is merged, we hope to add a SvelteKit starter-workflow, which they may require to be using replacement (for zero config purposes, but I'm not sure yet).

We can definitely wait on the automatic replacement workflow until after we propose a starter workflow and see what they say.


To use it, create a new [workflow](https://docs.github.com/en/actions/using-workflows/about-workflows) file at `.github/workflows/github-pages.yaml`. You can start with GitHub's [_Node.js CI_ template](https://github.com/actions/starter-workflows/blob/main/ci/node.js.yml), use the template provided here or make your own.

If you want to make your own workflow, it needs to perform these steps:

1. Checkout the repository with [`actions/checkout`](https://github.com/actions/checkout)
2. Setup Node.JS with [`actions/setup-node`](https://github.com/actions/setup-node)
3. Install dependencies with `npm i`, `pnpm i` or `yarn`
4. Setup SvelteKit for GitHub Pages with [`actions/configure-pages`](https://github.com/actions/configure-pages)
5. Build the website with `npm run build`, `pnpm run build` or `yarn run build`
6. Upload the built website with [`actions/upload-pages-artifact`](https://github.com/actions/upload-pages-artifact)
7. Deploy the uploaded website with [`actions/deploy-pages`](https://github.com/actions/deploy-pages)

Here's a complete template using [`pnpm`](https://pnpm.io).

```yaml
name: GitHub Pages

on:
push:
branches: [main]

jobs:
build:
runs-on: ubuntu-latest

strategy:
matrix:
node-version: [latest]

steps:
- uses: actions/checkout@v3

- uses: pnpm/action-setup@v2
with:
version: latest

- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
cache: pnpm

- name: Install dependencies
run: pnpm install

- uses: actions/configure-pages@v1

- name: Build
run: pnpm run build

- uses: actions/upload-pages-artifact@v1
with:
path: build

- uses: actions/deploy-pages@v1
```

#### Platform-specific context

Some adapters may have access to additional information about the request. For example, Cloudflare Workers can access an `env` object containing KV namespaces etc. This can be passed to the `RequestEvent` used in [hooks](/docs/hooks) and [server routes](/docs/routing#server) as the `platform` property — consult each adapter's documentation to learn more.
Expand Down
5 changes: 5 additions & 0 deletions packages/adapter-auto/adapters.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,10 @@ export const adapters = [
name: 'Netlify',
test: () => !!process.env.NETLIFY,
module: '@sveltejs/adapter-netlify'
},
{
name: 'GitHub Pages',
test: () => !!process.env.GITHUB_PAGES,
module: '@sveltejs/adapter-static'
}
];
1 change: 1 addition & 0 deletions packages/adapter-auto/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
"dependencies": {
"@sveltejs/adapter-cloudflare": "workspace:*",
"@sveltejs/adapter-netlify": "workspace:*",
"@sveltejs/adapter-static": "workspace:*",
"@sveltejs/adapter-vercel": "workspace:*"
},
"devDependencies": {
Expand Down
8 changes: 8 additions & 0 deletions packages/adapter-static/platforms.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,5 +78,13 @@ export const platforms = [
})
);
}
},
{
name: 'GitHub Pages',
test: () => !!process.env.GITHUB_PAGES,
defaults: () => ({
fallback: '404.html'
}),
done: (builder) => fs.writeFileSync(`${builder.config.kit.outDir}/.nojekyll`, '')
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From what I can tell, the new custom GitHub Actions Pages deployments don't need a .nojekyll file like publishing from a branch does. So, I think this can be removed since we're going with the new deployment method.

}
];
2 changes: 2 additions & 0 deletions pnpm-lock.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.