Cognito Auth

This library provides components and methods to allow a fast implementation of AWS Cognito authentication in Svelte applications.

It's optimized to work on the frontend!

Install

npm i cognito-auth-svelte

Usage

First of all, initiate the auth stores using the initAuth method at the root +layout.svelte file:

<script lang="ts">
	import { initAuth } from 'cognito-auth';

	const userPoolId = '...',
		clientId = '...';

	initAuth(userPoolId, clientId);
</script>

<slot />

Note that you can store your credentials at an .env file using VITE_ as a prefix on your variable names so they can be processed at compile time:

# .env
VITE_USERPOOL_ID="..."
VITE_CLIENT_ID="..."

<!-- +layout.svelte -->
<script lang="ts">
	import { initAuth } from 'cognito-auth';

	const userPoolId = import.meta.env.VITE_USERPOOL_ID,
		clientId = import.meta.env.VITE_CLIENT_ID;

	initAuth(userPoolId, clientId);
</script>

<slot />

source: https://vitejs.dev/guide/env-and-mode.html#env-files

Then, you can start using the library's custom components:

<script lang="ts">
	import { SignIn } from 'cognito-auth';

	// ...
</script>

<SignIn
	class="signIn"
	on:submit={handleSubmit}
	on:success={handleSuccess}
	on:error={handleError}
	on:finally={handleFinally}
	togglePassword
>
	<span slot="username">Your Username</span>
	<span slot="password">Your Password</span>
	<span slot="submit">
		{#if loading}
			loading...
		{:else}
			Sign In
		{/if}
	</span>
</SignIn>

If needed, you can also access the authStore store to retrieve specific user data, available when the user is authenticated.

Available components

| Component | Usage | | -------------- | --------------------------------------------------------------------------------------------------------------------- | | AuthGuard | Set at any +layout.svelte file to protect its child pages from unauthenticated users. | | SignIn | Lets users sign into your Cognito Userpool. | | SignUp | Lets users sign up to your Cognito Userpool. | | ConfirmSignUp | Used to send confirmation codes. Requires a username! | | ResetPassword | Allows users to change their password when required to. Use when users are created via Admin API. | | ChangePassword | Allows users to change their password when authenticated. If prompted by Cognito, prefer ResetPassword. | | ForgotPassword | Allows users to start the "forgot password" flow. Users must be confirmed and have a verified email or SMS attribute. | | SignOut | Signs users out of your Cognito Userpool. |

Some of those components emit custom events: | Component | Submit | Success | Error | Finally | Other | | --------- | ------ | ------- | ----- | ------- | ----- | | AuthGuard |❌|✅|✅|✅|❌| | SignIn |✅|✅|✅|✅|passwordReset| | SignUp |✅|✅|✅|✅|❌| | ConfirmSignUp |✅|✅|✅|✅|❌| | ResetPassword |✅|✅|✅|✅|❌| | ChangePassword |✅|✅|✅|✅|❌| | ForgotPassword* |✅|✅|✅|✅|❌| | SignOut |✅|✅|✅|✅|❌|

* ForgotPassword has duplicated events as it handles both the new password request and confirmation. This events are prefixed with request and confirm, respectively. E.g.: requestSuccess and confirmSuccess.

Available methods (@ authStore)

| Method | Usage | | ---------------------- | -------------------------------------------------------------------------------------------------- | | signUp | $authStore.signUp(username: string, password: string, attributes?: ICognitoUserAttributeData[])) | | confirmSignUp | $authStore.confirmSignUp(username: string, confirmationCode: string) | | resendConfirmationCode | $authStore.resendConfirmationCode(username: string) | | signIn | $authStore.signIn(username: string, password: string) | | passwordResetChallenge | $authStore.passwordResetChallenge(username: string, oldPassword: string, newPassword: string) | | signOut | $authStore.signOut(global = false) | | getAttributes | $authStore.getAttributes() | | updateAttributes | $authStore.updateAttributes(attributes: ICognitoUserAttributeData[]) | | changePassword | $authStore.changePassword(oldPassword: string, newPassword: string) | | forgotPassword | $authStore.forgotPassword(username: string) | | confirmPassword | $authStore.confirmPassword(username: string, code: string, newPassword: string) | | deleteUser | $authStore.deleteUser() |

Notes

This library aims to keep things simple and provide functionality over all things.

It might provide some minimal styles using TailwindCSS classes to streamline its implementation into your application.