{"id":13632593,"url":"https://github.com/happykit/auth-email","last_synced_at":"2025-04-18T02:33:43.020Z","repository":{"id":43891378,"uuid":"268106942","full_name":"happykit/auth-email","owner":"happykit","description":"🔐 Lightweight authentication specifically designed for Next.js","archived":true,"fork":false,"pushed_at":"2023-06-24T04:52:38.000Z","size":1954,"stargazers_count":73,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"next","last_synced_at":"2024-08-01T22:53:53.014Z","etag":null,"topics":["authentication","faunadb","nextjs","react"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/happykit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-05-30T15:27:31.000Z","updated_at":"2023-06-24T04:52:51.000Z","dependencies_parsed_at":"2024-04-16T11:05:30.325Z","dependency_job_id":null,"html_url":"https://github.com/happykit/auth-email","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happykit%2Fauth-email","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happykit%2Fauth-email/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happykit%2Fauth-email/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/happykit%2Fauth-email/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/happykit","download_url":"https://codeload.github.com/happykit/auth-email/tar.gz/refs/heads/next","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223772285,"owners_count":17199976,"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":["authentication","faunadb","nextjs","react"],"created_at":"2024-08-01T22:03:08.055Z","updated_at":"2024-11-09T00:31:42.171Z","avatar_url":"https://github.com/happykit.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003e ⚠ This was an experiment in Next.js authentication.\n\u003e\n\u003e It has since been deprecated. We recommend using [NextAuth.js](https://next-auth.js.org/) instead.\n\n\u003ca id=\"nav\"\u003e\n  \u003cimg src=\"https://i.imgur.com/fxD3HmM.png\" width=\"100%\" /\u003e\n\u003c/a\u003e\n\n\u003cdiv align=\"right\"\u003e\n  \u003ca href=\"https://auth-email-demo.now.sh/\"\u003eDemo\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;•\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://www.twitter.com/dferber90\" target=\"_blank\"\u003eTwitter\u003c/a\u003e\n\u003c/div\u003e\n\n\u0026nbsp;\n\u0026nbsp;\n\n\u003cp\u003eHappyAuth is an open-source account system specifically designed for Next.js applications. Users sign up with their email address and a password. HappyAuth supports server-side rendering and static pages. You can provide your own auth components or use our prebuilt ones. It's really easy to get up and running, and grows nicely alongside your application.\u003c/p\u003e\n\n### Key Features\n\n- A `useAuth` hook which returns the current user\n- An optional `getServerSideAuth` for server-side rendering\n- HappyAuth is tiny\n  - it adds only 4.6 kB to the first load JS\n  - it adds less than 0.04 kB if you're transitioning from another page\n- Extremely customizable\n  - Use the predefined authentication components or ship your own auth pages\n  - Special `triggers` allow you to hook into certain events\n  - You can even completely replace pages and api routes\n- All user data is stored in your own database\n  - Works with any database by adding a small database-specific driver\n  - You can run it on a free FaunaDB instance, which you can then also use for your app data\n  - We have a CLI which configures FaunaDB for you\n- Full TypeScript support with extensive types\n- OAuth support (authenticate using Facebook, GitHub etc)\n\n## The Gist\n\n```js\nimport { useAuth } from \"happyauth\"\n\nexport default function Home() {\n  const auth = useAuth()\n\n  if (auth.state === \"authenticating\") return \u003cp\u003eloading\u003c/p\u003e\n  return auth.state === \"signedIn\" ? (\n    \u003cp\u003eHi {auth.userId}\u003c/p\u003e\n  ) : (\n    \u003cp\u003eHi anonymous\u003c/p\u003e\n  )\n}\n```\n\nThe `useAuth` hook returns an authentication object. This object contains information about the current user. The `useAuth` function syncs the authentication state across all tabs.\n\nThe returned `auth` object not only contains data about the current user, but it also provides methods for `signUp`, `signIn` and so on.\n\nLet's now add server-side rendering support to our page.\n\n```js\nimport { useAuth } from \"happyauth\"\nimport { getServerSideAuth } from \"happyauth/server\"\n\nexport const getServerSideProps = async ({ req }) =\u003e {\n  const initialAuth = getServerSideAuth(req)\n  return { props: { initialAuth } }\n}\n\nexport default function Home(props) {\n  const auth = useAuth(props.initialAuth)\n\n  return auth.state === \"signedIn\" ? (\n    \u003cp\u003eHi {auth.userId}\u003c/p\u003e\n  ) : (\n    \u003cp\u003eHi anonymous\u003c/p\u003e\n  )\n}\n```\n\nWe are now prechecking the authenticated user on the server and passing that information down to the client. This allows us to get rid off the loading state. And more importantly, this gives us full access to the currently authenticated user inside `getServerSideProps`. We can prefetch any data we like based on that user and return it to as a prop. No more loading spinners!\n\nThe `getServerSideAuth` function is fast as it doesn't need to make a database query. It mainly decodes the JSON Web Token which gets passed to the server as a cookie.\n\n\u003e This package itself is mostly ready, however the documentation and the HappyKit website are still being built.\n\n## Quickstart\n\n\u003e This Quickstart focuses on FaunaDB, but HappyAuth works with other databases as well.\n\n\u003e HappyAuth is currently in alpha. You can use it to play around, but there are a few more breaking changes planned before the first stable release.\n\nWe provide an example application which you can use as the foundation of your project. You can use `create-next-app` to start a new project:\n\n```\nnpx create-next-app --example https://github.com/happykit/auth-email/tree/master/starter-fauna my-app\nor\nyarn create next-app --example https://github.com/happykit/auth-email/tree/master/starter-fauna my-app\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eTypeScript starter\u003c/summary\u003e\n\nIn case you're using TypeScript, you can use this starter instead:\n\n```\nnpx create-next-app --example https://github.com/happykit/auth-email/tree/master/starter-fauna-typescript my-app\nor\nyarn create next-app --example https://github.com/happykit/auth-email/tree/master/starter-fauna-typescript my-app\n```\n\n\u003c/details\u003e\n\n\u003e ~Check out our [documentation](https://docs.happykit.dev/) in case you want to add HappyAuth to an existing project. We provide a convenient CLI which adds the required files to your project in one step.~\n\u003e\n\u003e **Note:** The documentation site is still under construction. In the meantime, you can check out the README at this [commit](https://github.com/happykit/auth-email/blob/740a01395ab517c7e18fbed2751d6fbd5ff12d0c/README.md#setup) for the manual setup instructions. You'll need to install `@happykit/auth-email@1.0.0-alpha.4`.\n\n### Create a FaunaDB instance\n\nNext, you'll need to create a free FaunaDB instance. It takes around 3 minutes. No credit card is required.\n\nThe following steps will walk you through the setup of a free FaunaDB instance on [fauna.com](https://fauna.com/). That database will be used to store our user accounts. You can use it to store your applications information too.\n\nThere's a generous free tier and it doesn't require a credit card. You can sign in with GitHub.\n\n#### Create the database\n\n1. Open the [FaunaDB console](https://dashboard.fauna.com/) and sign in\n1. Click on \"New Database\", enter a name and click on \"Save\" to create your first database\n\n#### Create a key to access your database\n\n1. Now click on \"Security\" and then \"New key\"\n1. Change the Role to \"Server\"\n1. Enter a Key Name like \"Nextjs Application\"\n1. Click \"Save\"\n\nThat completes our database setup for now. We'll later use a script to create a User collection and an index.\n\n### The starter\n\nThe most important concept is that you'll usually not import from `@happykit/auth-email`. Instead, you'll import preconfigured functions from a local folder called `happyauth`. Your project is configured so that you can just do `import x from \"happyauth\"` and it will resolve to the local `happyauth` folder.\n\nWe do this to allow you to preconfigure certain functions and to enable Next.js to strip server-side code from the client bundle using its code removal feature.\n\nThe following files are included in your Next.js HappyAuth starter.\n\n#### `.env.local`\n\nThis file contains your secrets for local development.\n\nPaste in the `FAUNA_SERVER_KEY` which you created in the previous step.\n\nMake sure to replace the `HAPPYAUTH_TOKEN_SECRET` with a random value. You can execute `yarn auth-email random-secret` to create one.\n\nContents:\n\n```sh\nFAUNA_SERVER_KEY=\"fnxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\nHAPPYAUTH_TOKEN_SECRET=\"\u003crandom value\u003e\"\n```\n\n\u003e This file sets the environment variables for development. Make sure to provide these environment variables in your production application too. It's recommended to create a separate FaunaDB database for production, with its own secret. You can execute `yarn auth-email db init` to configure your production database. You don't need to worry about this now if you're just playing around locally.\n\n#### `happyauth/index.js`\n\nThis file contains the public configuration, which is shared with the clients. The file exports a preconfigured `useAuth` hook and the `publicConfig`.\n\nWhen you use `import { useAuth } from \"happyauth\"`, the import resolves to this file.\n\n#### `happyauth/server.js`\n\nThis file contains the server configuration. That configuration is not accessible to the clients. The file exports a preconfigured `getServerSideAuth` hook and the `serverConfig`.\n\nWhen you use `import { getServerSideAuth } from \"happyauth/server\"`, the import resolves to this file.\n\nThis file and `happyauth/index.js` are the two places where you usually configure HappyAuth.\n\n#### `pages/*.js`\n\nThese pages handle user authentication. They define the following routes:\n\n- `/change-password`\n- `/confirm-account`\n- `/forgot-password`\n- `/login`\n- `/reset-password`\n- `/signup`\n\n#### `pages/api/[...params].js`\n\nThis file defines a [Catch all API route](https://nextjs.org/docs/api-routes/dynamic-api-routes#catch-all-api-routes) which handles all requests to `/api/auth/*`.\n\n\u003cdetails\u003e\n\u003csummary\u003eLess important files\u003c/summary\u003e\n\n#### `pages/_app.js`\n\nHappyAuth needs an `AuthProvider` component which wraps your application. This component will ensure that you're only using one `useAuth` hook per page.\n\n#### `jsconfg.json` and `tsconfig.json`\n\nThese files enable importing from `happyauth` and treating it as if it was a regular package. This is done using [Absolute Imports](#configure-absolute-imports).\n\nThe JavaScript starter uses `jsconfig.json`, while the TypeScript starter uses `tsconfig.json`.\n\nThe configuration will map the following absolute imports to the files at the root:\n\n- `happyauth` to `/happyauth/index.js`\n- `happyauth/server` to `/happyauth/server.js`\n- `fauna-client` to `/fauna-client.js`\n\n\u003c/details\u003e\n\n### Running locally\n\nYou're now ready to run your app!\n\n```\nyarn dev\n```\n\nThen visit [localhost:3000](http://localhost:3000/) to see HappyAuth in action.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhappykit%2Fauth-email","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhappykit%2Fauth-email","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhappykit%2Fauth-email/lists"}