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

NatoBoram · 2022-08-07T03:26:58Z

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
This message body should clearly illustrate what problems it solves.
Ideally, include a test that fails without this PR but passes with it.

Publishing on GitHub Pages requires writing special checks on environment variables in order to select adapter-static.

/** @returns {import('@sveltejs/kit').Adapter} */
function adapter() {
	if (process.env.GITHUB_ACTIONS) return adapterStatic({ fallback: '404.html' });
	return adapterAuto();
}

This could be automated by adapter-auto. To make this possible, actions/configure-pages was modified to accommodate SvelteKit.

Add SvelteKit as an option for static_site_generator setting actions/configure-pages#16

This PR takes advantage of this recent modification to watch for $GITHUB_PAGES inside adapter-auto. By doing this, it becomes possible to publish to GitHub Pages from a GitHub Workflow without having to manually configure SvelteKit.

- 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

Tests

Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. All changesets should be patch until SvelteKit 1.0

changeset-bot · 2022-08-07T03:27:02Z

🦋 Changeset detected

Latest commit: 94d6594

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@sveltejs/adapter-auto	Patch
@sveltejs/adapter-static	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

packages/create-svelte/test/check.js

Rich-Harris

This is great, thanks — comment in line, I think we can probably make the setup more self-explanatory

Rich-Harris · 2022-08-16T17:16:35Z

documentation/docs/11-adapters.md

+SvelteKit can be automatically configured for deployment on GitHub Pages by using the `actions/configure-pages` GitHub Action before building it.
+
+```yaml
+- 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
+```


This could possibly use some more context — where do I put this code? Should we maybe have an example of a setting up a complete workflow, with instructions about where to write the .yml file etc?

Hi! Sorry it took this long, was busy at work. I added more information about GitHub Workflows.

GitHub Pages

SvelteKit can be automatically configured for deployment on GitHub Pages by using the 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.

To use it, create a new workflow file at .github/workflows/github-pages.yaml. You can start with GitHub's Node.js CI template, use the template provided here or make your own.

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

Checkout the repository with actions/checkout

Setup Node.JS with actions/setup-node

Install dependencies with npm i, pnpm i or yarn

Setup SvelteKit for GitHub Pages with actions/configure-pages

Build the website with npm run build, pnpm run build or yarn run build

Upload the built website with actions/upload-pages-artifact

Deploy the uploaded website with actions/deploy-pages

Here's a complete template using pnpm.

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

netlify · 2022-09-04T22:32:07Z

✅ Deploy Preview for kit-demo ready!

Name	Link
🔨 Latest commit	`94d6594`
🔍 Latest deploy log	https://app.netlify.com/sites/kit-demo/deploys/631528b18b27440008ce5527
😎 Deploy Preview	https://deploy-preview-5845--kit-demo.netlify.app/build
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

Rich-Harris

thank you! comments inline

Rich-Harris · 2022-09-05T02:34:48Z

documentation/docs/10-adapters.md

@@ -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


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

Rich-Harris · 2022-09-05T02:36:39Z

documentation/docs/10-adapters.md

@@ -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
+
+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.


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 ?? '' } } };

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.

AndrewLester · 2022-09-12T17:59:58Z

packages/adapter-static/platforms.js

+		defaults: () => ({
+			fallback: '404.html'
+		}),
+		done: (builder) => fs.writeFileSync(`${builder.config.kit.outDir}/.nojekyll`, '')


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.

AndrewLester · 2022-09-12T18:17:10Z

documentation/docs/10-adapters.md

@@ -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
+
+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.


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.

Rich-Harris · 2022-09-20T15:08:54Z

The more I wrap the head round this, the more I think we shouldn't do it. The whole point of adapter-auto is that it's zero config, but this isn't — the developer needs to add a workflow, and the workflow needs to use the correct package manager etc. And actions/configure-pages injecting the base path by manipulating svelte.config.js is just a horrible idea. Sorry.

I would rather we simply add some instructions to the adapter-static README (or somewhere in that package) that shows people how to configure paths.base and set up a workflow that uses actions/upload-pages-artifact and actions/deploy-pages (but not actions/configure-pages, which AFAICT isn't doing anything we need). Does that make sense?

Rich-Harris · 2022-09-21T18:56:33Z

Closing in favour of #6945 — thanks all

vercel bot deployed to Preview – kit August 7, 2022 03:27 View deployment

vercel bot deployed to Preview – kit August 7, 2022 03:34 View deployment

vercel bot deployed to Preview – kit August 7, 2022 03:53 View deployment

vercel bot deployed to Preview – kit August 7, 2022 04:24 View deployment

vercel bot deployed to Preview – kit August 7, 2022 04:45 View deployment

NatoBoram marked this pull request as ready for review August 7, 2022 04:45

Conduitry reviewed Aug 7, 2022

View reviewed changes

packages/create-svelte/test/check.js Outdated Show resolved Hide resolved

NatoBoram mentioned this pull request Aug 7, 2022

Accept a run parameter to build the artifact before publishing it actions/upload-pages-artifact#9

Closed

benmccann added the pkg:adapter-auto label Aug 9, 2022

vercel bot deployed to Preview – kit August 10, 2022 03:03 View deployment

NatoBoram mentioned this pull request Aug 13, 2022

Add SvelteKit as an option for static_site_generator setting actions/configure-pages#16

Merged

vercel bot deployed to Preview – kit August 16, 2022 02:49 View deployment

vercel bot deployed to Preview – kit August 16, 2022 03:15 View deployment

Rich-Harris reviewed Aug 16, 2022

View reviewed changes

vercel bot deployed to Preview – kit-svelte-dev August 16, 2022 21:14 View deployment

vercel bot deployed to Preview – kit September 4, 2022 22:32 View deployment

NatoBoram and others added 10 commits September 4, 2022 18:34

Detected environment: GitHub Pages. Using @sveltejs/adapter-static

5f85f56

Add a changeset file

1e998b8

Add @sveltejs/adapter-static to @sveltejs/adapter-auto's dependencies

dda286b

Add default config for adapter-static on GH Pages

afb15ea

Set GITHUB_ACTIONS: undefined for testing

a5a3986

Add a .nojekyll when building for GitHub Pages

beefcb2

📝 Add doc on GitHub Pages

d0e91ca

Use $GITHUB_PAGES

2bb0550

New changeset since no longer editing create-svelte

ca7a09d

📝 More instructions on using GitHub Pages

bae8090

vercel bot deployed to Preview – kit September 4, 2022 22:34 View deployment

🎨 Convert indentation to spaces

94d6594

vercel bot deployed to Preview – kit September 4, 2022 22:37 View deployment

NatoBoram requested review from Conduitry and Rich-Harris and removed request for Conduitry and Rich-Harris September 4, 2022 23:18

Rich-Harris requested changes Sep 5, 2022

View reviewed changes

j4w8n mentioned this pull request Sep 8, 2022

Error: writeStatic has been removed. Please ensure you are using the latest version of svelte-adapter-github j4w8n/svelte-adapter-github#2

Closed

AndrewLester reviewed Sep 12, 2022

View reviewed changes

Rich-Harris mentioned this pull request Sep 21, 2022

Add documentation on how to deploy to GitHub Pages #6945

Closed

Rich-Harris closed this Sep 21, 2022

gtm-nayan mentioned this pull request Jun 2, 2023

docs: improve deploy-to-github-pages action example #10083

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

NatoBoram commented Aug 7, 2022 •

edited

Loading

changeset-bot bot commented Aug 7, 2022 •

edited

Loading

Rich-Harris left a comment

Rich-Harris Aug 16, 2022

NatoBoram Sep 4, 2022

netlify bot commented Sep 4, 2022 •

edited

Loading

Rich-Harris left a comment

Rich-Harris Sep 5, 2022

Rich-Harris Sep 5, 2022

AndrewLester Sep 12, 2022

AndrewLester Sep 12, 2022

AndrewLester Sep 12, 2022

Rich-Harris commented Sep 20, 2022

Rich-Harris commented Sep 21, 2022

		@@ -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

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

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

Conversation

NatoBoram commented Aug 7, 2022 • edited Loading

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Changesets

changeset-bot bot commented Aug 7, 2022 • edited Loading

🦋 Changeset detected

Rich-Harris left a comment

Choose a reason for hiding this comment

Rich-Harris Aug 16, 2022

Choose a reason for hiding this comment

NatoBoram Sep 4, 2022

Choose a reason for hiding this comment

GitHub Pages

netlify bot commented Sep 4, 2022 • edited Loading

✅ Deploy Preview for kit-demo ready!

Rich-Harris left a comment

Choose a reason for hiding this comment

Rich-Harris Sep 5, 2022

Choose a reason for hiding this comment

Rich-Harris Sep 5, 2022

Choose a reason for hiding this comment

AndrewLester Sep 12, 2022

Choose a reason for hiding this comment

AndrewLester Sep 12, 2022

Choose a reason for hiding this comment

AndrewLester Sep 12, 2022

Choose a reason for hiding this comment

Rich-Harris commented Sep 20, 2022

Rich-Harris commented Sep 21, 2022

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

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

NatoBoram commented Aug 7, 2022 •

edited

Loading

changeset-bot bot commented Aug 7, 2022 •

edited

Loading

netlify bot commented Sep 4, 2022 •

edited

Loading