{"id":22009692,"url":"https://github.com/zitadel/typescript","last_synced_at":"2025-04-05T14:03:50.803Z","repository":{"id":167161514,"uuid":"622995060","full_name":"zitadel/typescript","owner":"zitadel","description":"Typescript packages and application to showcase the ZITADEL resource API","archived":false,"fork":false,"pushed_at":"2025-04-04T09:11:34.000Z","size":9583,"stargazers_count":81,"open_issues_count":43,"forks_count":49,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-04T10:21:48.501Z","etag":null,"topics":["login","login-component","proto-client","sdk","typescript"],"latest_commit_sha":null,"homepage":"https://typescript-login.vercel.app","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/zitadel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-03T13:37:01.000Z","updated_at":"2025-04-04T09:02:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"c443e884-6fcb-48be-91b0-dda01aab496a","html_url":"https://github.com/zitadel/typescript","commit_stats":null,"previous_names":["zitadel/typescript"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Ftypescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Ftypescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Ftypescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zitadel%2Ftypescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zitadel","download_url":"https://codeload.github.com/zitadel/typescript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345850,"owners_count":20924102,"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":["login","login-component","proto-client","sdk","typescript"],"created_at":"2024-11-30T02:10:24.843Z","updated_at":"2025-04-05T14:03:50.782Z","avatar_url":"https://github.com/zitadel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZITADEL TypeScript with Turborepo\n\nThis repository contains all TypeScript and JavaScript packages and applications you need to create your own ZITADEL\nLogin UI.\n\n\u003cimg src=\"./apps/login/screenshots/collage.png\" alt=\"collage of login screens\" width=\"1600px\" /\u003e\n\n[![npm package](https://img.shields.io/npm/v/@zitadel/proto.svg?style=for-the-badge\u0026logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/@zitadel/proto)\n[![npm package](https://img.shields.io/npm/v/@zitadel/client.svg?style=for-the-badge\u0026logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/@zitadel/client)\n\n**⚠️ This repo and packages are in beta state and subject to change ⚠️**\n\nThe scope of functionality of this repo and packages is under active development.\n\nThe `@zitadel/client` package is using [@connectrpc/connect](https://github.com/connectrpc/connect-es#readme).\n\nYou can read the [contribution guide](/CONTRIBUTING.md) on how to contribute.\nQuestions can be raised in our [Discord channel](https://discord.gg/erh5Brh7jE) or as\na [GitHub issue](https://github.com/zitadel/typescript/issues).\n\n## Developing Your Own ZITADEL Login UI\n\nWe think the easiest path of getting up and running, is the following:\n\n1. Fork and clone this repository\n1. [Run the ZITADEL Cloud login UI locally](#run-login-ui)\n1. Make changes to the code and see the effects live on your local machine\n1. Study the rest of this README.md and get familiar and comfortable with how everything works.\n1. Decide on a way of how you want to build and run your login UI.\n   You can reuse ZITADEL Clouds way.\n   But if you need more freedom, you can also import the packages you need into your self built application.\n\n## Included Apps And Packages\n\n- `login`: The login UI used by ZITADEL Cloud, powered by Next.js\n- `@zitadel/client`: shared client utilities for node and browser environments\n- `@zitadel/proto`: Protocol Buffers (proto) definitions used by ZITADEL projects\n- `@zitadel/tsconfig`: shared `tsconfig.json`s used throughout the monorepo\n- `@zitadel/eslint-config`: ESLint preset\n\nEach package and app is 100% [TypeScript](https://www.typescriptlang.org/).\n\n### Login\n\nThe login is currently in a work in progress state.\nThe goal is to implement a login UI, using the session API of ZITADEL, which also implements the OIDC Standard and is\nready to use for everyone.\n\nIn the first phase we want to have a MVP login ready with the OIDC Standard and a basic feature set. In a second step\nthe features will be extended.\n\nThis list should show the current implementation state, and also what is missing.\nYou can already use the current state, and extend it with your needs.\n\n#### Features list\n\n- [x] Local User Registration (with Password)\n- [x] User Registration and Login with external Provider\n  - [x] Google\n  - [x] GitHub\n  - [x] GitHub Enterprise\n  - [x] GitLab\n  - [x] GitLab Enterprise\n  - [x] Azure\n  - [x] Apple\n  - [x] Generic OIDC\n  - [x] Generic OAuth\n  - [ ] Generic JWT\n  - [ ] LDAP\n  - [ ] SAML SP\n- Multifactor Registration an Login\n  - [x] Passkeys\n  - [x] TOTP\n  - [x] OTP: Email Code\n  - [x] OTP: SMS Code\n- [ ] Password Change/Reset\n- [x] Domain Discovery\n- [x] Branding\n- OIDC Standard\n\n  - [x] Authorization Code Flow with PKCE\n  - [x] AuthRequest `hintUserId`\n  - [x] AuthRequest `loginHint`\n  - [x] AuthRequest `prompt`\n    - [x] Login\n    - [x] Select Account\n    - [ ] Consent\n    - [x] Create\n  - Scopes\n    - [x] `openid email profile address``\n    - [x] `offline access`\n    - [x] `urn:zitadel:iam:org:idp:id:{idp_id}`\n    - [x] `urn:zitadel:iam:org:project:id:zitadel:aud`\n    - [x] `urn:zitadel:iam:org:id:{orgid}`\n    - [x] `urn:zitadel:iam:org:domain:primary:{domain}`\n  - [ ] AuthRequest UI locales\n\n  #### Flow diagram\n\n  This diagram shows the available pages and flows.\n\n  \u003e Note that back navigation or retries are not displayed.\n\n```mermaid\n    flowchart TD\n    A[Start] --\u003e register\n    A[Start] --\u003e accounts\n    A[Start] --\u003e loginname\n    loginname -- signInWithIDP --\u003e idp-success\n    loginname -- signInWithIDP --\u003e idp-failure\n    idp-success --\u003e B[signedin]\n    loginname --\u003e password\n    loginname -- hasPasskey --\u003e passkey\n    loginname -- allowRegister --\u003e register\n    passkey-add --passwordAllowed --\u003e password\n    passkey -- hasPassword --\u003e password\n    passkey --\u003e B[signedin]\n    password -- hasMFA --\u003e mfa\n    password -- allowPasskeys --\u003e passkey-add\n    password -- reset --\u003e password-set\n    email -- reset --\u003e password-set\n    password-set --\u003e B[signedin]\n    password-change --\u003e B[signedin]\n    password -- userstate=initial --\u003e password-change\n\n    mfa --\u003e otp\n    otp --\u003e B[signedin]\n    mfa--\u003e u2f\n    u2f --\u003eB[signedin]\n    register -- password/passkey --\u003e B[signedin]\n    password --\u003e B[signedin]\n    password-- forceMFA --\u003emfaset\n    mfaset --\u003e u2fset\n    mfaset --\u003e otpset\n    u2fset --\u003e B[signedin]\n    otpset --\u003e B[signedin]\n    accounts--\u003e loginname\n    password -- not verified yet --\u003everify\n    register-- withpassword --\u003everify\n    passkey-- notVerified --\u003e verify\n    verify --\u003e B[signedin]\n```\n\nYou can find a more detailed documentation of the different pages [here](./apps/login/readme.md).\n\n## Tooling\n\n- [TypeScript](https://www.typescriptlang.org/) for static type checking\n- [ESLint](https://eslint.org/) for code linting\n- [Prettier](https://prettier.io) for code formatting\n\n## Useful Commands\n\n- `pnpm generate` - Build proto stubs for server and client package\n- `pnpm build` - Build all packages and the login app\n- `pnpm test` - Test all packages and the login app\n- `pnpm test:watch` - Rerun tests on file change\n- `pnpm dev` - Develop all packages and the login app\n- `pnpm lint` - Lint all packages\n- `pnpm changeset` - Generate a changeset\n- `pnpm clean` - Clean up all `node_modules` and `dist` folders (runs each package's clean script)\n\n## Versioning And Publishing Packages\n\nPackage publishing has been configured using [Changesets](https://github.com/changesets/changesets).\nHere is their [documentation](https://github.com/changesets/changesets#documentation) for more information about the\nworkflow.\n\nThe [GitHub Action](https://github.com/changesets/action) needs an `NPM_TOKEN` and `GITHUB_TOKEN` in the repository\nsettings. The [Changesets bot](https://github.com/apps/changeset-bot) should also be installed on the GitHub repository.\n\nRead the [changesets documentation](https://github.com/changesets/changesets/blob/main/docs/automating-changesets.md)\nfor more information about this automation\n\n### Run Login UI\n\nTo run the application make sure to install the dependencies with\n\n```sh\npnpm install\n```\n\nthen generate the GRPC stubs with\n\n```sh\npnpm generate\n```\n\nTo run the application against a local ZITADEL instance, run the following command:\n\n```sh\npnpm run-zitadel\n```\n\nThis sets up ZITADEL using docker compose and writes the configuration to the file `apps/login/.env.local`.\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternatively, use another environment\u003c/summary\u003e\nYou can develop against any ZITADEL instance in which you have sufficient rights to execute the following steps.\nJust create or overwrite the file `apps/login/.env.local` yourself.\nAdd your instances base URL to the file at the key `ZITADEL_API_URL`.\nGo to your instance and create a service user for the login application.\nThe login application creates users on your primary organization and reads policy data.\nFor the sake of simplicity, just make the service user an instance member with the role `IAM_OWNER`.\nCreate a PAT and copy it to the file `apps/login/.env.local` using the key `ZITADEL_SERVICE_USER_TOKEN`.\n\nThe file should look similar to this:\n\n```\nZITADEL_API_URL=https://zitadel-tlx3du.us1.zitadel.cloud\nZITADEL_SERVICE_USER_TOKEN=1S6w48thfWFI2klgfwkCnhXJLf9FQ457E-_3H74ePQxfO3Af0Tm4V5Xi-ji7urIl_xbn-Rk\n```\n\n\u003c/details\u003e\n\nStart the login application in dev mode:\n\n```sh\npnpm dev\n```\n\nOpen the login application with your favorite browser at `localhost:3000`.\nChange the source code and see the changes live in your browser.\n\nMake sure the application still behaves as expected by running all tests\n\n```sh\npnpm test\n```\n\nTo satisfy your unique workflow requirements, check out the package.json in the root directory for more detailed scripts.\n\n### Run Login UI Acceptance tests\n\nTo run the acceptance tests you need a running ZITADEL environment and a component which receives HTTP requests for the emails and sms's.\nThis component should also be able to return the content of these notifications, as the codes and links are used in the login flows.\nThere is a basic implementation in Golang available under [the sink package](./acceptance/sink).\n\nTo setup ZITADEL with the additional Sink container for handling the notifications:\n\n```sh\npnpm run-sink\n```\n\nThen you can start the acceptance tests with:\n\n```sh\npnpm test:acceptance\n```\n\n### Deploy to Vercel\n\nTo deploy your own version on Vercel, navigate to your instance and create a service user.\nThen create a personal access token (PAT), copy and set it as ZITADEL_SERVICE_USER_TOKEN, then navigate to your instance\nsettings and make sure it gets IAM_OWNER permissions.\nFinally set your instance url as ZITADEL_API_URL. Make sure to set it without trailing slash.\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fzitadel%2Ftypescript\u0026env=ZITADEL_API_URL,ZITADEL_SERVICE_USER_TOKEN\u0026root-directory=apps/login\u0026envDescription=Setup%20a%20service%20account%20with%20IAM_LOGIN_CLIENT%20membership%20on%20your%20instance%20and%20provide%20its%20personal%20access%20token.\u0026project-name=zitadel-login\u0026repository-name=zitadel-login)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Ftypescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzitadel%2Ftypescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzitadel%2Ftypescript/lists"}