From efe4d12986790d96369c17ec9584d60562c4fd92 Mon Sep 17 00:00:00 2001 From: Antoine BERNIER Date: Sun, 7 Jul 2024 17:29:51 +0200 Subject: [PATCH 1/2] new pages workflow --- .github/workflows/pages.yml | 55 +++++++++++++++++ README.md | 40 ++++++++---- components/Image.tsx | 6 +- faq/github-pages-deployment.md | 108 --------------------------------- next.config.js | 7 +++ 5 files changed, 95 insertions(+), 121 deletions(-) create mode 100644 .github/workflows/pages.yml delete mode 100644 faq/github-pages-deployment.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000000..b2e5a34214 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,55 @@ +# Inspired from https://github.com/actions/starter-workflows/blob/main/pages/nextjs.yml +name: GitHub Pages + +on: + push: + branches: main + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: 'pages' + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + cache: yarn + - id: configurepages + uses: actions/configure-pages@v5 + - name: Restore cache + uses: actions/cache@v4 + with: + path: .next/cache + key: ${{ runner.os }}-nextjs-${{ hashFiles('**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }} + restore-keys: | + ${{ runner.os }}-nextjs-${{ hashFiles('**/yarn.lock') }}- + - run: yarn + - run: yarn build + env: + EXPORT: 1 + UNOPTIMIZED: 1 + BASE_PATH: ${{ steps.configurepages.outputs.base_path }} + - uses: actions/upload-pages-artifact@v3 + with: + path: ./out + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index a7bae41669..af1219cb14 100644 --- a/README.md +++ b/README.md @@ -269,33 +269,49 @@ canonicalUrl: https://tailwind-nextjs-starter-blog.vercel.app/blog/introducing-t ## Deploy -**Vercel** +### GitHub Pages + +A [`pages.yml`](.github/workflows/pages.yml) workflow is already provided. Simply select "GitHub Actions" in: `Settings > Pages > Build and deployment > Source`. + +### Vercel + The easiest way to deploy the template is to deploy on [Vercel](https://vercel.com). Check out the [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. -**Netlify** +### Netlify + [Netlify](https://www.netlify.com/)’s Next.js runtime configures enables key Next.js functionality on your website without the need for additional configurations. Netlify generates serverless functions that will handle Next.js functionalities such as server-side rendered (SSR) pages, incremental static regeneration (ISR), `next/images`, etc. See [Next.js on Netlify](https://docs.netlify.com/integrations/frameworks/next-js/overview/#next-js-runtime) for suggested configuration values and more details. -**Static hosting services / GitHub Pages / S3 / Firebase etc.** +### Static hosting services (GitHub Pages / S3 / Firebase etc.) + +Run: + +```sh +$ EXPORT=1 UNOPTIMIZED=1 yarn build +``` + +Then, deploy the generated `out` folder or run `npx serve out` it locally. -1. Add `output: 'export'` in `next.config.js`. See [static exports documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#configuration) for more information. -2. Comment out `headers()` from `next.config.js`. -3. Add `unoptimized: true` to the `images` key in `next.config.js`: +> [!IMPORTANT] +> If deploying with a URL base path, like https://example.org/myblog you need an extra `BASE_PATH` shell-var to the build command: +> +> ```sh +> $ EXPORT=1 UNOPTIMIZED=1 BASE_PATH=/myblog yarn build +> ``` - Alternatively, to continue using `next/image`, you can use an alternative image optimization provider such as Imgix, Cloudinary or Akamai. See [image optimization documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#image-optimization) for more details. +> [!TIP] +> Alternatively to `UNOPTIMIZED=1`, to continue using `next/image`, you can use an alternative image optimization provider such as Imgix, Cloudinary or Akamai. See [image optimization documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#image-optimization) for more details. -4. Remove `api` folder and components which call the server-side function such as the Newsletter component. Not technically required and the site will build successfully, but the APIs cannot be used as they are server-side functions. -5. Run `yarn build`. The generated static content is in the `out` folder. -6. Deploy the `out` folder to your hosting service of choice or run `npx serve out` to view the website locally. +Optionnally: -**Note**: Deploying on Github pages require addition modifications to the base path. Please refer to the FAQ for more information. +1. Comment out `headers()` from `next.config.js`. +2. Remove `api` folder and components which call the server-side function such as the Newsletter component. Not technically required and the site will build successfully, but the APIs cannot be used as they are server-side functions. ## Frequently Asked Questions - [How can I add a custom MDX component?](/faq/custom-mdx-component.md) - [How can I customize the `kbar` search?](/faq/customize-kbar-search.md) -- [How do I deploy on Github pages?](/faq/github-pages-deployment.md) ## Support diff --git a/components/Image.tsx b/components/Image.tsx index fde277acc3..968094aa26 100644 --- a/components/Image.tsx +++ b/components/Image.tsx @@ -1,5 +1,9 @@ import NextImage, { ImageProps } from 'next/image' -const Image = ({ ...rest }: ImageProps) => +const basePath = process.env.BASE_PATH + +const Image = ({ src, ...rest }: ImageProps) => ( + +) export default Image diff --git a/faq/github-pages-deployment.md b/faq/github-pages-deployment.md deleted file mode 100644 index 9b8439dcf2..0000000000 --- a/faq/github-pages-deployment.md +++ /dev/null @@ -1,108 +0,0 @@ -# How do I deploy on Github pages? - -[Demo](https://timlrx.github.io/tailwind-nextjs-starter-blog/) & [Source](https://github.com/timlrx/tailwind-nextjs-starter-blog/tree/test-gh-pages-static) - -1. Follow the section on creating a static build in the main README and test it locally to ensure that it works. -2. Specify the base path in `next.config.js` to match your repository name e.g. `basePath: "/tailwind-nextjs-starter-blog"`. -3. Modify `component/Image.tsx` to use the correct base path for the image source: - - ```tsx - import NextImage, { ImageProps } from 'next/image' - - const Image = ({ src, ...rest }: ImageProps) => ( - - ) - - export default Image - ``` - -4. To automate deployment, here's a Github action that you could use - -```yml -# Sample workflow for building and deploying a Next.js site to GitHub Pages -# -# To get started with Next.js see: https://nextjs.org/docs/getting-started -# -name: Deploy Next.js site to Pages - -on: - # Runs on pushes targeting the default branch - push: - branches: ['test-gh-pages-static'] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: 'pages' - cancel-in-progress: false - -jobs: - # Build job - build: - name: Build Nextjs Blog - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v3 - - name: Detect package manager - id: detect-package-manager - run: | - if [ -f "${{ github.workspace }}/yarn.lock" ]; then - echo "manager=yarn" >> $GITHUB_OUTPUT - echo "command=install" >> $GITHUB_OUTPUT - echo "runner=yarn" >> $GITHUB_OUTPUT - exit 0 - elif [ -f "${{ github.workspace }}/package.json" ]; then - echo "manager=npm" >> $GITHUB_OUTPUT - echo "command=ci" >> $GITHUB_OUTPUT - echo "runner=npx --no-install" >> $GITHUB_OUTPUT - exit 0 - else - echo "Unable to determine package manager" - exit 1 - fi - - name: Setup Node - uses: actions/setup-node@v3 - with: - node-version: '18' - cache: ${{ steps.detect-package-manager.outputs.manager }} - - name: Restore cache - uses: actions/cache@v3 - with: - path: | - .next/cache - # Generate a new cache whenever packages or source files change. - key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }} - # If source files changed but packages didn't, rebuild from a prior cache. - restore-keys: | - ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}- - - name: Install dependencies - run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }} - - name: Build project assets - run: ${{ steps.detect-package-manager.outputs.manager }} build - - name: Upload artifact - uses: actions/upload-pages-artifact@v2 - with: - path: ./out - - # Deployment job - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v2 -``` diff --git a/next.config.js b/next.config.js index 31db627b7a..86acba3d7a 100644 --- a/next.config.js +++ b/next.config.js @@ -54,12 +54,18 @@ const securityHeaders = [ }, ] +const output = process.env.EXPORT ? 'export' : undefined +const basePath = process.env.BASE_PATH || undefined +const unoptimized = process.env.UNOPTIMIZED ? true : undefined + /** * @type {import('next/dist/next-server/server/config').NextConfig} **/ module.exports = () => { const plugins = [withContentlayer, withBundleAnalyzer] return plugins.reduce((acc, next) => next(acc), { + output, + basePath, reactStrictMode: true, pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'], eslint: { @@ -72,6 +78,7 @@ module.exports = () => { hostname: 'picsum.photos', }, ], + unoptimized, }, async headers() { return [ From 8b446d30f9b18c8100336f7dc73ab5c5c6c3d8da Mon Sep 17 00:00:00 2001 From: Timothy Date: Wed, 10 Jul 2024 21:55:47 +0800 Subject: [PATCH 2/2] Clarify features that cannot be used in static build --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index af1219cb14..e455d0c6cc 100644 --- a/README.md +++ b/README.md @@ -303,7 +303,7 @@ Then, deploy the generated `out` folder or run `npx serve out` it locally. > [!TIP] > Alternatively to `UNOPTIMIZED=1`, to continue using `next/image`, you can use an alternative image optimization provider such as Imgix, Cloudinary or Akamai. See [image optimization documentation](https://nextjs.org/docs/app/building-your-application/deploying/static-exports#image-optimization) for more details. -Optionnally: +Consider removing the following features that cannot be used in a static build: 1. Comment out `headers()` from `next.config.js`. 2. Remove `api` folder and components which call the server-side function such as the Newsletter component. Not technically required and the site will build successfully, but the APIs cannot be used as they are server-side functions.