{"id":13468541,"url":"https://github.com/netlify/next-on-netlify","last_synced_at":"2025-03-26T05:31:11.910Z","repository":{"id":51710142,"uuid":"236359408","full_name":"netlify/next-on-netlify","owner":"netlify","description":"Build and deploy Next.js applications with Server-Side Rendering on Netlify!","archived":true,"fork":false,"pushed_at":"2021-05-10T15:48:17.000Z","size":2466,"stargazers_count":718,"open_issues_count":1,"forks_count":67,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-03-21T20:44:19.492Z","etag":null,"topics":["lambda-functions","netlify","netlify-deployment","netlify-functions","next-on-netlify","nextjs","server-side-rendering","serverless"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netlify.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-26T18:50:31.000Z","updated_at":"2025-03-15T14:19:04.000Z","dependencies_parsed_at":"2022-08-03T09:00:48.814Z","dependency_job_id":null,"html_url":"https://github.com/netlify/next-on-netlify","commit_stats":null,"previous_names":["finnwoelm/next-on-netlify"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fnext-on-netlify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fnext-on-netlify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fnext-on-netlify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netlify%2Fnext-on-netlify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netlify","download_url":"https://codeload.github.com/netlify/next-on-netlify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245597243,"owners_count":20641861,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lambda-functions","netlify","netlify-deployment","netlify-functions","next-on-netlify","nextjs","server-side-rendering","serverless"],"created_at":"2024-07-31T15:01:13.129Z","updated_at":"2025-03-26T05:31:10.319Z","avatar_url":"https://github.com/netlify.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"## Deprecating next-on-netlify\n\nWe are deprecating `next-on-netlify` in favor of Netlify's [Essential Next.js Build Plugin](https://github.com/netlify/netlify-plugin-nextjs). Please visit [this issue](https://github.com/netlify/next-on-netlify/issues/176) to learn more about the deprecation of `next-on-netlify` and ask any questions. You can also visit our simple [Migration doc](https://github.com/netlify/next-on-netlify/blob/main/MIGRATING.md) for assistance migrating to the plugin.\n\n- Build Plugin [@netlify/plugin-nextjs](https://github.com/netlify/netlify-plugin-nextjs)\n- [Plugin npm package](https://www.npmjs.com/package/@netlify/plugin-nextjs)\n\n![Next.js on Netlify](next-on-netlify.png)\n\n\u003cp align=\"center\"\u003e\n  \u003ca aria-label=\"npm version\" href=\"https://www.npmjs.com/package/next-on-netlify\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/npm/v/next-on-netlify\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"MIT License\" href=\"https://img.shields.io/npm/l/next-on-netlify\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/npm/l/next-on-netlify\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"npm downloads\" href=\"https://www.npmjs.com/package/next-on-netlify\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/npm/dt/next-on-netlify\"\u003e\n  \u003c/a\u003e\n  \u003ca aria-label=\"Tested with Cypress\" href=\"https://www.cypress.io/\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/badge/tested%20with-Cypress-04C38E.svg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n`next-on-netlify` is a utility for enabling server-side rendering in Next.js on Netlify. It wraps your application in a tiny compatibility layer, so that pages can use Netlify Functions to be server-side rendered.\n\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Setup](#setup)\n  - [1. Set Next.js target to serverless](#1-set-nextjs-target-to-serverless)\n  - [2. Add postbuild hook](#2-add-postbuild-hook)\n  - [3. Configure for Netlify](#3-configure-for-netlify)\n    - [(Optional) Configure private git submodules](#optional-configure-private-git-submodules)\n- [Demo](#demo)\n- [Optional Extras](#optional-extras)\n  - [Preview Locally](#preview-locally)\n  - [Custom Netlify Redirects](#custom-netlify-redirects)\n  - [Custom Netlify Functions](#custom-netlify-functions)\n  - [Background Functions](#background-functions)\n  - [Using Netlify Identity](#using-netlify-identity)\n- [Caveats](#caveats)\n  - [Fallbacks for Pages with `getStaticPaths`](#fallbacks-for-pages-with-getstaticpaths)\n  - [next/image](#nextimage)\n- [Credits](#credits)\n- [Showcase](#showcase)\n\n\n## Installation\n\n```\nnpm install --save next-on-netlify\n```\n\n## Setup\n\n### 1. Set Next.js target to serverless\n\nWe must build our Next.js app as a serverless app. You can read more about serverless Next.js [here](https://nextjs.org/docs/api-reference/next.config.js/build-target#serverless-target).\n\nIt's super simple. Just create a `next.config.js` file in the root of your project and write the following:\n\n```js\n// next.config.js\n\nmodule.exports = {\n  // Target must be serverless\n  target: \"serverless\",\n};\n```\n\nIf binaries are needed in the deployment the following configuration is needed ([Prisma](https://github.com/prisma/prisma) is an example):\n\n```js\n// next.config.js\n\nmodule.exports = {\n  // Target must be experimental-serverless-trace\n  // Your build time will be longer with this option\n  target: \"experimental-serverless-trace\",\n};\n```\n\n### 2. Add postbuild hook\n\nThe next-on-netlify package adds the `next-on-netlify` command. When we run this command, some magic happens to prepare our Next.js app for hosting on Netlify\\*.\n\nWe want the next-on-netlify command to run after we build our Next.js application. So let's add a postbuild hook to our package.json file. You should add `\"postbuild\": \"next-on-netlify\"` to the existing scripts, like so:\n\n\n```\n{\n  \"name\": \"my-nextjs-app\",\n  \"scripts\": {\n    \"dev\": \"next\",\n    \"build\": \"next build\",\n    \"postbuild\": \"next-on-netlify\"\n  },\n  ...\n}\n```\n\n\\*If you're curious about the \"magic\", check out the well-documented [`next-on-netlify.js` file](https://github.com/netlify/next-on-netlify/blob/master/next-on-netlify.js).\n\n### 3. Configure for Netlify\n\nWe're almost done! We just have to tell Netlify how to build our Next.js app, where the functions folder is located, and which folder to upload to its CDN. We do that with a `netlify.toml` file in the root of your project and the following instructions:\n\n```toml\n[build]\n  command   = \"npm run build\"\n  functions = \"out_functions\"\n  publish   = \"out_publish\"\n```\n\nNote: `out_functions` and `out_publish` are hard-coded into next-on-netlify.\nThese are not configurable at the moment.\n\n#### (Optional) Configure private git submodules\nIf your project contains private submodules, in order to deploy it, you will\nneed to:\n\n1. [Generate a Deploy\n   Key](https://docs.netlify.com/configure-builds/repo-permissions-linking/#deploy-keys)\n   in Netlify and [add it to the relevant\n   submodules](https://docs.github.com/en/developers/overview/managing-deploy-keys#setup-2)\n   so that they can be cloned during the deploy process.\n\n2. Ensure the submodule remotes are set to SSH format (i.e.\n   `git@github.com:owner/project.git`, not `https://...`). Inside the submodule\n   directory, the git remote can be updated with: \n\n   ```bash\n   # git remote set-url [remote] [url]\n   git remote set-url origin git@github.com:owner/project.git\n   ```\n\nWe're done. Let's deploy 🚀🚀🚀\n\nIf you're not familiar with Netlify, follow the deployment instructions here: https://www.netlify.com/blog/2020/11/30/how-to-deploy-next.js-sites-to-netlify/\n\n## Demo\n\n- Site: https://next-on.netlify.com/\n- Code: https://github.com/netlify-labs/next-on-netlify-demo\n\n## Optional Extras\n\n### Preview Locally\n\nI recommend you still use `next dev` to build and preview your application locally.\n\nBut if you want to emulate the Netlify deployment on your computer, you can also run `next-on-netlify` locally and then use `netlify-cli` to preview the result.\n\nFirst, install the latest version of `netlify-cli` (you can also [look at package.json](https://github.com/netlify/next-on-netlify/blob/master/package.json) to see the version that next-on-netlify has been tested against):\n\n```bash\nnpm install -g netlify-cli\n```\n\nThen, add the following `[dev]` block to your `netlify.toml`:\n\n```toml\n# netlify.toml\n\n# [build]\n#   ...\n\n[dev]\n  functions = \"out_functions\"\n  publish   = \"out_publish\"\n  # We manually set the framework to static, otherwise Netlify automatically\n  # detects Next.js and redirects do not work.\n  # Read more: https://github.com/netlify/cli/blob/master/docs/netlify-dev.md#project-detection\n  framework = \"#static\"\n```\n\nLastly, add the following lines to your `.gitignore`:\n\n```shell\n# .gitignore\n\n# Files generated by next-on-netlify command\n/out_publish/\n/out_functions/\n```\n\nNow you're all set.\n\nFrom now on, whenever you want to preview your application locally, just run:\n\n1. `npx next-on-netlify watch`: This will run `next build` to build your Next.js app and `next-on-netlify` to prepare your Next.js app for compatibility with Netlify. Any source code changes will trigger another build.\n1. `netlify dev`: This will emulate Netlify on your computer and let you preview your app on `http://localhost:8888`.\n\n*Note:*\n\nPreview Mode is not yet available locally, running `netlify dev`, for static pages without revalidate or fallback. This will be supported soon.\n\nFor now, Preview Mode *is* supported in production for all Next.js page types.\n\n### Custom Netlify Redirects\n\nYou can define custom redirects in a `_redirects` and/or in your `netlify.toml` file.\nThe precedence of these rules are:\n\n- `_redirects`\n- `next-on-netlify` redirects\n\nCurrently, there is no support for redirects set in your `netlify.toml` file.\n\n[Read more about Netlify redirects here](https://docs.netlify.com/routing/redirects/).\n\n### Custom Netlify Functions\n\n`next-on-netlify` creates one Netlify Function for each of your\nSSR pages and API endpoints. Currently, you can only create custom Netlify functions using [@netlify/plugin-nextjs](https://github.com/netlify/netlify-plugin-nextjs#custom-netlify-functions).\n\n### Background Functions\n\nIf your Next.js API page/route ends in `-background`, it will be treated as a [Netlify background function](https://docs.netlify.com/functions/background-functions/).\nNote: background functions are only available on certain plans.\n\n### Using Netlify Identity\n\nYou can use [Netlify Identity](https://docs.netlify.com/visitor-access/identity/) with `next-on-netlify`. For all pages with server-side rendering (getInitialProps*, getServerSideProps, and API routes), you can access the [clientContext object](https://docs.netlify.com/functions/functions-and-identity/#access-identity-info-via-clientcontext) via the `req` parameter.\n\nFor example:\n\n```js\nconst Page = () =\u003e \u003cp\u003eHello World!\u003c/p\u003e;\n\nexport const getServerSideProps = async ({ req }) =\u003e {\n  // Get event and context from Netlify Function\n  const {\n    netlifyFunctionParams: { event, context },\n  } = req;\n\n  // Access Netlify identity\n  const { identity, user } = context.clientContext;\n\n  return {\n    props: {},\n  };\n};\n\nexport default Page;\n```\n\nTo access Netlify Identity from pages without server-side rendering, you can create a [Next API route](https://nextjs.org/docs/api-routes/introduction) that performs identity-related logic:\n\n```js\nexport default async function getUser(req, res) {\n  // Get event and context from Netlify Function\n  const {\n    netlifyFunctionParams: { event, context },\n  } = req;\n\n  // Access Netlify identity\n  const { user } = context.clientContext;\n\n  // Respond with user object\n  res.json({ user });\n}\n```\n\n\\* Note that pages using getInitialProps are only server-side rendered on initial page load and not when the user navigates client-side between pages.\n\n\n## Caveats\n\n### Fallbacks for Pages with `getStaticPaths`\n\n[Fallback pages](https://nextjs.org/docs/basic-features/data-fetching#fallback-true) behave differently with `next-on-netlify` than they do with Next.js. On Next.js, when navigating to a path that is not defined in `getStaticPaths`, it first displays the fallback page. Next.js then generates the HTML in the background and caches it for future requests.\n\nWith `next-on-netlify`, when navigating to a path that is not defined in `getStaticPaths`, it server-side renders the page and sends it directly to the user. The user never sees the fallback page. The page is not cached for future requests.\n\nFor more on this, see: [Issue #7](https://github.com/netlify/next-on-netlify/issues/7#issuecomment-636883539)\n\n### next/image\n\nOur existing solution for next/image is not very performant. We have performance improvements on our roadmap, dependent on internal work.\n\nTo get better performance now, we recommend using a cloud provider like Cloudinary ([see the Next.js docs](https://nextjs.org/docs/basic-features/image-optimization#loader)).\n\n## Credits\n\nThis package is maintained by [Lindsay Levine](https://github.com/lindsaylevine), [Finn Woelm](https://github.com/FinnWoelm), and [Cassidy Williams](https://github.com/cassidoo).\n\n📣 Shoutout to [@mottox2](https://github.com/mottox2) (a pioneer of hosting Next.js on Netlify) and [@danielcondemarin](https://github.com/danielcondemarin) (author of serverless-next.js for AWS). The two were big inspirations for this package.\n\n🙌 Big \"thank you\" to the following people for their contributions, support, and beta testing:\n\n- [@spencewood](https://github.com/spencewood)\n- [@alxhghs](https://github.com/alxhghs)\n- [@gamliela](https://github.com/gamliela)\n- [@wei](https://github.com/wei)\n- [@laugharn](https://github.com/laugharn)\n- [@rajington](https://github.com/rajington)\n- [@etrepum](https://github.com/etrepum)\n- [@jonasbuntinx](https://github.com/jonasbuntinx)\n- [@joostmeijles](https://github.com/joostmeijles)\n\n\n## Showcase\n\nThe following sites are built with `next-on-netlify`:\n\n![opinionatedreact.com](https://raw.githubusercontent.com/netlify/next-on-netlify/master/assets/showcase-opinionatedreact.png)  \n[opinionatedreact.com](https://opinionatedreact.com/) ([via Twitter](https://twitter.com/NikkitaFTW/status/1302667952920162309))\n\n![missionbit.org](https://raw.githubusercontent.com/netlify/next-on-netlify/master/assets/showcase-missionbit.png)  \n[missionbit.org](https://www.missionbit.org/) ([#18](https://github.com/netlify/next-on-netlify/pull/18#issuecomment-643828966))\n\n![gemini.com](https://user-images.githubusercontent.com/6261646/99102161-4efc8100-25a3-11eb-96ce-81192a3602a9.png)\n\n[gemini.com](https://gemini.com/)\n\n![bigbinary.com](https://raw.githubusercontent.com/netlify/next-on-netlify/main/assets/showcase-bigbinary.png)\n\n[bigbinary.com](https://bigbinary.com/)\n\n[![next-cms-ghost](https://static.gotsby.org/v1/assets/images/next-cms-ghost-demo.png)](https://netlify.jamify.org)\n\n[Create your own blog and deploy to Netlify!](https://github.com/styxlab/next-cms-ghost)\n\nAre you building something awesome with `next-on-netlify`? 🔥 Let us know and we will feature it here :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetlify%2Fnext-on-netlify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetlify%2Fnext-on-netlify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetlify%2Fnext-on-netlify/lists"}