@auth/solid-start 0.1.2 → 0.1.3

package/client.d.ts

@@ -24,14 +24,21 @@ type SignInAuthorizationParams = string | string[][] | Record<string, string> |
  * or send the user to the signin page listing all possible providers.
  * Automatically adds the CSRF token to the request.
  *
- * [Documentation](https://next-auth.js.org/getting-started/client#signin)
+ * ```ts
+ * import { signIn } from "@auth/solid-start/client"
+ * signIn()
+ * signIn("provider") // example: signIn("github")
+ * ```
  */
 declare function signIn<P extends RedirectableProviderType | undefined = undefined>(providerId?: LiteralUnion<P extends RedirectableProviderType ? P | BuiltInProviderType : BuiltInProviderType>, options?: SignInOptions, authorizationParams?: SignInAuthorizationParams): Promise<Response | undefined>;
 /**
  * Signs the user out, by removing the session cookie.
  * Automatically adds the CSRF token to the request.
  *
- * [Documentation](https://next-auth.js.org/getting-started/client#signout)
+ * ```ts
+ * import { signOut } from "@auth/solid-start/client"
+ * signOut()
+ * ```
  */
 declare function signOut(options?: SignOutParams): Promise<void>;
 

package/client.js

@@ -1,3 +1,6 @@
+import {
+  __name
+} from "./chunk-HXRSFH6L.js";
 async function signIn(providerId, options, authorizationParams) {
   const { callbackUrl = window.location.href, redirect = true } = options ?? {};
   const isCredentials = providerId === "credentials";
@@ -29,6 +32,7 @@ async function signIn(providerId, options, authorizationParams) {
   }
   return res;
 }
+__name(signIn, "signIn");
 async function signOut(options) {
   const { callbackUrl = window.location.href } = options ?? {};
   const csrfTokenResponse = await fetch("/api/auth/csrf");
@@ -50,6 +54,7 @@ async function signOut(options) {
   if (url.includes("#"))
     window.location.reload();
 }
+__name(signOut, "signOut");
 export {
   signIn,
   signOut

package/index.d.ts

@@ -1,5 +1,25 @@
 import { AuthConfig, Session } from '@auth/core/types';
 
+/**
+ *
+ * :::warning
+ * `@auth/solid-start` is currently experimental. The API _will_ change in the future.
+ * :::
+ *
+ * SolidStart Auth is the official SolidStart integration for Auth.js.
+ * It provides a simple way to add authentication to your SolidStart app in a few lines of code.
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn
+ * npm install @auth/core @auth/solid-start
+ * ```
+ *
+ * We recommended to using [create-jd-app](https://github.com/OrJDev/create-jd-app)
+ *
+ * @module index
+ */
+
 interface SolidAuthConfig extends AuthConfig {
     /**
      * Defines the base path for the auth routes.
@@ -7,6 +27,182 @@ interface SolidAuthConfig extends AuthConfig {
      */
     prefix?: string;
 }
+/**
+ * ## Setup
+ *
+ * [Generate an auth secret](https://generate-secret.vercel.app/32), then set it as an environment variable:
+ *
+ * ```
+ * AUTH_SECRET=your_auth_secret
+ * ```
+ *
+ * ## Creating the API handler
+ *
+ * in this example we are using github so make sure to set the following environment variables:
+ *
+ * ```
+ * GITHUB_ID=your_github_oauth_id
+ * GITHUB_SECRET=your_github_oauth_secret
+ * ```
+ *
+ * ```ts
+ * // routes/api/auth/[...solidauth].ts
+ * import { SolidAuth, type SolidAuthConfig } from "@auth/solid-start"
+ * import GitHub from "@auth/core/providers/github"
+ *
+ * export const authOpts: SolidAuthConfig = {
+ *   providers: [
+ *     GitHub({
+ *       clientId: process.env.GITHUB_ID,
+ *       clientSecret: process.env.GITHUB_SECRET,
+ *     }),
+ *   ],
+ *   debug: false,
+ * }
+ *
+ * export const { GET, POST } = SolidAuth(authOpts)
+ * ```
+ *
+ * ## Getting the current session
+ *
+ * ```ts
+ * import { getSession } from "@auth/solid-start"
+ * import { createServerData$ } from "solid-start/server"
+ * import { authOpts } from "~/routes/api/auth/[...solidauth]"
+ *
+ * export const useSession = () => {
+ *   return createServerData$(
+ *     async (_, { request }) => {
+ *       return await getSession(request, authOpts)
+ *     },
+ *     { key: () => ["auth_user"] }
+ *   )
+ * }
+ *
+ * // useSession returns a resource:
+ * const session = useSession()
+ * const loading = session.loading
+ * const user = () => session()?.user
+ * ```
+ * ## Protected Routes
+ *
+ * ### When Using SSR
+ *
+ * When using SSR, I recommend creating a `Protected` component that will trigger suspense using the `Show` component. It should look like this:
+ *
+ *
+ * ```tsx
+ * // components/Protected.tsx
+ * import { type Session } from "@auth/core/types";
+ * import { getSession } from "@auth/solid-start";
+ * import { Component, Show } from "solid-js";
+ * import { useRouteData } from "solid-start";
+ * import { createServerData$, redirect } from "solid-start/server";
+ * import { authOpts } from "~/routes/api/auth/[...solidauth]";
+ *
+ * const Protected = (Comp: IProtectedComponent) => {
+ *   const routeData = () => {
+ *     return createServerData$(
+ *       async (_, event) => {
+ *         const session = await getSession(event.request, authOpts);
+ *         if (!session || !session.user) {
+ *           throw redirect("/");
+ *         }
+ *         return session;
+ *       },
+ *       { key: () => ["auth_user"] }
+ *     );
+ *   };
+ *
+ *   return {
+ *     routeData,
+ *     Page: () => {
+ *       const session = useRouteData<typeof routeData>();
+ *       return (
+ *         <Show when={session()} keyed>
+ *           {(sess) => <Comp {...sess} />}
+ *         </Show>
+ *       );
+ *     },
+ *   };
+ * };
+ *
+ * type IProtectedComponent = Component<Session>;
+ *
+ * export default Protected;
+ * ```
+ *
+ * It can be used like this:
+ *
+ *
+ * ```tsx
+ * // routes/protected.tsx
+ * import Protected from "~/components/Protected";
+ *
+ * export const { routeData, Page } = Protected((session) => {
+ *   return (
+ *     <main class="flex flex-col gap-2 items-center">
+ *       <h1>This is a protected route</h1>
+ *     </main>
+ *   );
+ * });
+ *
+ * export default Page;
+ * ```
+ *
+ * ### When Using CSR
+ *
+ * When using CSR, the `Protected` component will not work as expected and will cause the screen to flash, so I had to come up with a tricky solution, we will use a Solid-Start middleware:
+ *
+ * ```tsx
+ * // entry-server.tsx
+ * import { Session } from "@auth/core";
+ * import { getSession } from "@auth/solid-start";
+ * import { redirect } from "solid-start";
+ * import {
+ *   StartServer,
+ *   createHandler,
+ *   renderAsync,
+ * } from "solid-start/entry-server";
+ * import { authOpts } from "./routes/api/auth/[...solidauth]";
+ *
+ * const protectedPaths = ["/protected"]; // add any route you wish in here
+ *
+ * export default createHandler(
+ *   ({ forward }) => {
+ *     return async (event) => {
+ *       if (protectedPaths.includes(new URL(event.request.url).pathname)) {
+ *         const session = await getSession(event.request, authOpts);
+ *         if (!session) {
+ *           return redirect("/");
+ *         }
+ *       }
+ *       return forward(event);
+ *     };
+ *   },
+ *   renderAsync((event) => <StartServer event={event} />)
+ * );
+ * ```
+ *
+ * And now you can easily create a protected route:
+ *
+ *
+ * ```tsx
+ * // routes/protected.tsx
+ * export default () => {
+ *   return (
+ *     <main class="flex flex-col gap-2 items-center">
+ *       <h1>This is a protected route</h1>
+ *     </main>
+ *   );
+ * };
+ * ```
+ *
+ * :::note
+ * The CSR method should also work when using SSR, the SSR method shouldn't work when using CSR
+ * :::
+ *
+ */
 declare function SolidAuth(config: SolidAuthConfig): {
     GET(event: any): Promise<Response | undefined>;
     POST(event: any): Promise<Response | undefined>;

package/index.js

@@ -1,3 +1,6 @@
+import {
+  __name
+} from "./chunk-HXRSFH6L.js";
 import { Auth } from "@auth/core";
 const actions = [
   "providers",
@@ -20,6 +23,7 @@ function SolidAuthHandler(prefix, authOptions) {
     return await Auth(request, authOptions);
   };
 }
+__name(SolidAuthHandler, "SolidAuthHandler");
 function SolidAuth(config) {
   const { prefix = "/api/auth", ...authOptions } = config;
   authOptions.secret ??= process.env.AUTH_SECRET;
@@ -34,14 +38,14 @@ function SolidAuth(config) {
     }
   };
 }
+__name(SolidAuth, "SolidAuth");
 async function getSession(req, options) {
   options.secret ??= process.env.AUTH_SECRET;
   options.trustHost ??= true;
   const url = new URL("/api/auth/session", req.url);
-  const response = await Auth(
-    new Request(url, { headers: req.headers }),
-    options
-  );
+  const response = await Auth(new Request(url, {
+    headers: req.headers
+  }), options);
   const { status = 200 } = response;
   const data = await response.json();
   if (!data || !Object.keys(data).length)
@@ -50,6 +54,7 @@ async function getSession(req, options) {
     return data;
   throw new Error(data.message);
 }
+__name(getSession, "getSession");
 export {
   SolidAuth,
   getSession

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@auth/solid-start",
   "description": "Authentication for SolidStart.",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "files": [
     "client.*",
@@ -22,17 +22,17 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@auth/core": "0.18.1"
+  },
   "devDependencies": {
     "@solidjs/meta": "^0.28.0",
     "@types/node": "^18.7.14",
     "solid-js": "^1.5.7",
     "solid-start": "^0.2.14",
-    "tsup": "^6.5.0",
-    "typescript": "5.2.2",
-    "@auth/core": "0.16.0"
+    "tsup": "^6.5.0"
   },
   "peerDependencies": {
-    "@auth/core": "~0.2.2 || ^0.2.2",
     "solid-js": "^1.5.7",
     "solid-start": "^0.2.14"
   },

package/src/client.ts

@@ -35,7 +35,11 @@ export type SignInAuthorizationParams =
  * or send the user to the signin page listing all possible providers.
  * Automatically adds the CSRF token to the request.
  *
- * [Documentation](https://next-auth.js.org/getting-started/client#signin)
+ * ```ts
+ * import { signIn } from "@auth/solid-start/client"
+ * signIn()
+ * signIn("provider") // example: signIn("github")
+ * ```
  */
 export async function signIn<
   P extends RedirectableProviderType | undefined = undefined
@@ -96,7 +100,10 @@ export async function signIn<
  * Signs the user out, by removing the session cookie.
  * Automatically adds the CSRF token to the request.
  *
- * [Documentation](https://next-auth.js.org/getting-started/client#signout)
+ * ```ts
+ * import { signOut } from "@auth/solid-start/client"
+ * signOut()
+ * ```
  */
 export async function signOut(options?: SignOutParams) {
   const { callbackUrl = window.location.href } = options ?? {}

package/src/index.ts

@@ -1,3 +1,23 @@
+/**
+ *
+ * :::warning
+ * `@auth/solid-start` is currently experimental. The API _will_ change in the future.
+ * :::
+ *
+ * SolidStart Auth is the official SolidStart integration for Auth.js.
+ * It provides a simple way to add authentication to your SolidStart app in a few lines of code.
+ *
+ * ## Installation
+ *
+ * ```bash npm2yarn
+ * npm install @auth/core @auth/solid-start
+ * ```
+ *
+ * We recommended to using [create-jd-app](https://github.com/OrJDev/create-jd-app)
+ *
+ * @module index
+ */
+
 import { Auth } from "@auth/core"
 import type { AuthAction, AuthConfig, Session } from "@auth/core/types"
 
@@ -36,6 +56,182 @@ function SolidAuthHandler(prefix: string, authOptions: SolidAuthConfig) {
   }
 }
 
+/**
+ * ## Setup
+ *
+ * [Generate an auth secret](https://generate-secret.vercel.app/32), then set it as an environment variable:
+ *
+ * ```
+ * AUTH_SECRET=your_auth_secret
+ * ```
+ *
+ * ## Creating the API handler
+ *
+ * in this example we are using github so make sure to set the following environment variables:
+ *
+ * ```
+ * GITHUB_ID=your_github_oauth_id
+ * GITHUB_SECRET=your_github_oauth_secret
+ * ```
+ *
+ * ```ts
+ * // routes/api/auth/[...solidauth].ts
+ * import { SolidAuth, type SolidAuthConfig } from "@auth/solid-start"
+ * import GitHub from "@auth/core/providers/github"
+ *
+ * export const authOpts: SolidAuthConfig = {
+ *   providers: [
+ *     GitHub({
+ *       clientId: process.env.GITHUB_ID,
+ *       clientSecret: process.env.GITHUB_SECRET,
+ *     }),
+ *   ],
+ *   debug: false,
+ * }
+ *
+ * export const { GET, POST } = SolidAuth(authOpts)
+ * ```
+ *
+ * ## Getting the current session
+ *
+ * ```ts
+ * import { getSession } from "@auth/solid-start"
+ * import { createServerData$ } from "solid-start/server"
+ * import { authOpts } from "~/routes/api/auth/[...solidauth]"
+ *
+ * export const useSession = () => {
+ *   return createServerData$(
+ *     async (_, { request }) => {
+ *       return await getSession(request, authOpts)
+ *     },
+ *     { key: () => ["auth_user"] }
+ *   )
+ * }
+ *
+ * // useSession returns a resource:
+ * const session = useSession()
+ * const loading = session.loading
+ * const user = () => session()?.user
+ * ```
+ * ## Protected Routes
+ *
+ * ### When Using SSR
+ *
+ * When using SSR, I recommend creating a `Protected` component that will trigger suspense using the `Show` component. It should look like this:
+ *
+ *
+ * ```tsx
+ * // components/Protected.tsx
+ * import { type Session } from "@auth/core/types";
+ * import { getSession } from "@auth/solid-start";
+ * import { Component, Show } from "solid-js";
+ * import { useRouteData } from "solid-start";
+ * import { createServerData$, redirect } from "solid-start/server";
+ * import { authOpts } from "~/routes/api/auth/[...solidauth]";
+ *
+ * const Protected = (Comp: IProtectedComponent) => {
+ *   const routeData = () => {
+ *     return createServerData$(
+ *       async (_, event) => {
+ *         const session = await getSession(event.request, authOpts);
+ *         if (!session || !session.user) {
+ *           throw redirect("/");
+ *         }
+ *         return session;
+ *       },
+ *       { key: () => ["auth_user"] }
+ *     );
+ *   };
+ *
+ *   return {
+ *     routeData,
+ *     Page: () => {
+ *       const session = useRouteData<typeof routeData>();
+ *       return (
+ *         <Show when={session()} keyed>
+ *           {(sess) => <Comp {...sess} />}
+ *         </Show>
+ *       );
+ *     },
+ *   };
+ * };
+ *
+ * type IProtectedComponent = Component<Session>;
+ *
+ * export default Protected;
+ * ```
+ *
+ * It can be used like this:
+ *
+ *
+ * ```tsx
+ * // routes/protected.tsx
+ * import Protected from "~/components/Protected";
+ *
+ * export const { routeData, Page } = Protected((session) => {
+ *   return (
+ *     <main class="flex flex-col gap-2 items-center">
+ *       <h1>This is a protected route</h1>
+ *     </main>
+ *   );
+ * });
+ *
+ * export default Page;
+ * ```
+ *
+ * ### When Using CSR
+ *
+ * When using CSR, the `Protected` component will not work as expected and will cause the screen to flash, so I had to come up with a tricky solution, we will use a Solid-Start middleware:
+ *
+ * ```tsx
+ * // entry-server.tsx
+ * import { Session } from "@auth/core";
+ * import { getSession } from "@auth/solid-start";
+ * import { redirect } from "solid-start";
+ * import {
+ *   StartServer,
+ *   createHandler,
+ *   renderAsync,
+ * } from "solid-start/entry-server";
+ * import { authOpts } from "./routes/api/auth/[...solidauth]";
+ *
+ * const protectedPaths = ["/protected"]; // add any route you wish in here
+ *
+ * export default createHandler(
+ *   ({ forward }) => {
+ *     return async (event) => {
+ *       if (protectedPaths.includes(new URL(event.request.url).pathname)) {
+ *         const session = await getSession(event.request, authOpts);
+ *         if (!session) {
+ *           return redirect("/");
+ *         }
+ *       }
+ *       return forward(event);
+ *     };
+ *   },
+ *   renderAsync((event) => <StartServer event={event} />)
+ * );
+ * ```
+ *
+ * And now you can easily create a protected route:
+ *
+ *
+ * ```tsx
+ * // routes/protected.tsx
+ * export default () => {
+ *   return (
+ *     <main class="flex flex-col gap-2 items-center">
+ *       <h1>This is a protected route</h1>
+ *     </main>
+ *   );
+ * };
+ * ```
+ *
+ * :::note
+ * The CSR method should also work when using SSR, the SSR method shouldn't work when using CSR
+ * :::
+ *
+ */
 export function SolidAuth(config: SolidAuthConfig) {
   const { prefix = "/api/auth", ...authOptions } = config
   authOptions.secret ??= process.env.AUTH_SECRET