dimsee

v0.6.8

Published

5 months ago

Modern, flexible authentication solution for MERN applications with OAuth support

0High
0Medium
0Low

sidd190

mern auth authentication react express mongodb oauth google-auth github-auth session jwt

Dimsee: Full-Stack Authentication Solution 🎨

Dimsee is a powerful, ready-to-use authentication package for MERN stack applications. It provides a secure, customizable backend and a beautiful, themeable React frontend component to handle user registration, login, and session management with ease.

🚀 Features

Backend

🔐 Local Authentication: Standard email/password signup and signin.
🌐 OAuth 2.0: Support for Google and GitHub.
🍪 Session Management: Secure, cookie-based sessions using JWT and express-session.
🛡️ Secure Passwords: Password hashing with bcrypt.js.
⚙️ Easy Configuration: Simple to configure via a single config object.
🚧 Route Protection: Middleware to protect your API routes.

Frontend

⚛️ React Component: A single AuthForm component for all your auth needs.
🔄 Multiple Modes: Supports both 'signin' and 'signup' modes.
🎨 Themable Designs: Comes with three built-in themes: modern, minimal, and colorful.
🔗 OAuth Integration: Buttons for Google/GitHub login that activate based on backend configuration.
🛠️ Customizable: Easily extend and style with your own CSS.
📞 Callbacks: onSuccess and onError callbacks for handling auth events.

📚 Table of Contents

🚀 Getting Started

Installation

npm install dimsee

Basic Usage

Here is a quick example of how to set up a basic authentication system with Dimsee by running a standalone backend server.

Backend (server.js):

const { createAuthBackend } = require('dimsee/backend');

const app = createAuthBackend({
  mongoUri: process.env.MONGO_URI,
  jwtSecret: process.env.JWT_SECRET,
  corsOrigin: 'http://localhost:3000', // Your frontend URL
});

const PORT = process.env.PORT || 5000;
app.listen(PORT, () => console.log(`🚀 Server running on port ${PORT}`));

Frontend (App.js):

import {AuthProvider} from 'dimsee/frontend';
import {AuthForm} from 'dimsee/frontend';

function App() {
  return (
    <AuthProvider apiUrl="http://localhost:5000/api/auth">
      <div className="App">
        <AuthForm
          design="modern"
          onSuccess={(data) => console.log('Auth Success:', data)}
          onError={(error) => console.error('Auth Error:', error)}
        />
      </div>
    </AuthProvider>
  );
}

📖 Framework Guides

Learn how to integrate Dimsee with popular React frameworks.

Create React App / Vite

For projects bootstrapped with Create React App or Vite, the setup is straightforward. You run the Dimsee backend as a separate server and connect your frontend to it.

Set up the Backend: Use the code from the Basic Usage section to create your server.js.
Environment Variables: In your CRA/Vite project root, create a .env file.
- Vite: VITE_API_URL=http://localhost:5000/api/auth
- Create React App: REACT_APP_API_URL=http://localhost:5000/api/auth
Configure AuthProvider: In your main App.js or main.jsx, wrap your app with AuthProvider and pass the API URL from your environment variables.
```
// Example for Vite
<AuthProvider apiUrl={import.meta.env.VITE_API_URL}>
  <App />
</AuthProvider>
```

Next.js

With Next.js, you have two primary options for the backend:

(Recommended) Run a standalone backend server just like with CRA/Vite. This is the simplest and most scalable approach.
(Advanced) Integrate the backend directly into Next.js API Routes.

Option 2: Integrated API Route

If you prefer an all-in-one setup, you can run the Dimsee backend inside a catch-all API route.

Create API Route: Create a file at pages/api/auth/[...slug].js (or app/api/auth/[...slug]/route.js for App Router).

// file: pages/api/auth/[...slug].js
import { createAuthBackend } from 'dimsee/backend';
    
// Initialize the backend once
const authApp = createAuthBackend({
    mongoUri: process.env.MONGO_URI,
    jwtSecret: process.env.JWT_SECRET,
    corsOrigin: process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000',
});
    
// Disable Next.js's default body parser for this route
export const config = {
    api: {
        bodyParser: false,
    },
};

export default function handler(req, res) {
    // Rewrite the URL to remove the `/api/auth` prefix
    req.url = req.url.replace('/api/auth', '');
    // Let the Dimsee Express app handle the request
    return authApp(req, res);
}

Configure Frontend: In your _app.js (or layout.js for App Router), wrap your application with the AuthProvider. The apiUrl now points to your internal API route.

// file: pages/_app.js
import {AuthProvider} from 'dimsee/frontend';
    
function MyApp({ Component, pageProps }) {
  return (
    <AuthProvider apiUrl="/api/auth">
      <Component {...pageProps} />
    </AuthProvider>
  );
}
    
export default MyApp;

Use Client Components: Any component that uses AuthForm or AuthStatus must be a Client Component. Add 'use client'; to the top of the file if you are using the Next.js App Router.

Frontend: `AuthForm` Component

The AuthForm component is the core of the Dimsee frontend. It is a highly configurable React component that handles user interaction for both signing in and signing up.

Props

| Prop | Type | Default | Description | |---------------|------------|------------------------------|----------------------------------------------------------------------------------------------------------| | mode | string | 'signin' | Determines if the form is in 'signin' or 'signup' mode. | | design | string | 'modern' | The visual theme of the form. Options: 'modern', 'minimal', 'colorful'. | | onSuccess | function | undefined | Callback function executed on successful authentication. Receives response data. | | onError | function | undefined | Callback function executed on authentication failure. Receives the error object. | | className | string | '' | Additional CSS classes to apply to the component's root element for custom styling. | | oAuthConfig | object | null | An object to dynamically configure OAuth providers on the frontend. | | redirectUrl | string | null | A URL to redirect to after a successful OAuth login. | | onModeChange| function | undefined | A function to make the form a controlled component, managing the mode from a parent component. |

Frontend Components: `AuthStatus` vs. `AuthForm`

Dimsee provides two key frontend components: AuthStatus and AuthForm. Understanding their differences is key to using the package effectively.

AuthForm is a low-level component focused on one thing: displaying a sign-in or sign-up form.
AuthStatus is a high-level component that acts as a "controller." It checks if a user is logged in and, based on that status, decides what to render: the AuthForm, a logout button, or your application's content.

Use Case Comparison

| Scenario | Recommended Component | Why? | |-----------------------------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------| | A dedicated /login page | AuthForm | You just need to show the form, as the user is guaranteed to be unauthenticated on this page. | | A popup modal for login/signup | AuthForm | You control when the modal appears, so you just need the form itself inside the modal. | | A simple drop-in for an entire app | AuthStatus | It will handle everything automatically: show the login form if logged out, and your app content if logged in. | | A header that shows "Login" or "Logout" | AuthStatus | It can automatically switch between showing a login prompt (AuthForm) and a LogoutButton based on auth state. |

Using `AuthStatus`

AuthStatus is the easiest way to get started. It wraps your authenticated application content and handles the entire authentication flow.

Basic Example: Protecting App Content

If a user is not logged in, AuthStatus will render the AuthForm. Once they log in, it will render the content passed to it as children.

import { AuthStatus } from 'dimsee/frontend';

function App() {
  return (
    <AuthProvider apiUrl="http://localhost:5000/api/auth">
      <AuthStatus>
        {/* This content will only be shown to authenticated users */}
        <div>
          <h1>Welcome to the App!</h1>
          <p>This is a protected area.</p>
        </div>
      </AuthStatus>
    </AuthProvider>
  );
}

Advanced Example: Showing User Info and Set Password Button

AuthStatus also automatically includes the LogoutButton and can conditionally show the SetPasswordButton for users who signed up with an OAuth provider.

import { AuthStatus } from 'dimsee/frontend';

function App() {
  return (
    <AuthProvider apiUrl="http://localhost:5000/api/auth">
      <AuthStatus
        showUserInfo={true}          // Shows username next to logout button
        showSetPassword={true}       // Shows a "Set Password" button if needed
        logoutDesign="minimal"
      >
        {/* Your protected app content here */}
      </AuthStatus>
    </AuthProvider>
  );
}

`AuthStatus` Props

| Prop | Type | Default | Description | |----------------------------|-----------|-------------|------------------------------------------------------------------------------------------| | showForm | boolean | true | If true, renders AuthForm when the user is not authenticated. | | formMode | string | 'signin' | The default mode for the nested AuthForm. | | formDesign | string | 'modern' | The design theme for the nested AuthForm. | | logoutDesign | string | 'modern' | The design theme for the LogoutButton. | | showUserInfo | boolean | true | If true, displays the user's name next to the logout button. | | showSetPassword | boolean | false | If true, displays a SetPasswordButton for authenticated users without a password. | | children | node | undefined | The content to display when the user is authenticated. | | unauthenticatedComponent | node | undefined | A custom component to show instead of AuthForm when the user is not authenticated. |

For more granular control over logout and set password button positioning and styling, refer to their individual component files.

Backend: `createAuthBackend`

The createAuthBackend function sets up and returns a fully configured Express application with all the necessary middleware and routes for authentication.

Configuration Options

| Option | Type | Default | Description | |---------------|----------|-----------------------------------|-----------------------------------------------------------------------------| | mongoUri | string | 'mongodb://localhost:27017/mern-auth' | The connection string for your MongoDB database. | | jwtSecret | string | 'your-secret-key-...' | A secret key for signing JWTs. Change this in production. | | corsOrigin | string | 'http://localhost:5173' | The origin to allow for CORS requests (your frontend URL). | | cookieMaxAge| number | 604800000 (7 days) | The max age for the authentication cookie in milliseconds. | | enableOAuth | boolean| false | A flag to enable or disable OAuth functionality. | | oauth | object | {} | An object containing credentials for OAuth providers (Google, GitHub). |

Protecting Routes

The package also exports an authMiddleware that you can use to protect your own API routes.

const { createAuthBackend, authMiddleware } = require('dimsee/backend');
const app = createAuthBackend(...);

app.get('/api/my-protected-route', authMiddleware, (req, res) => {
  // This will only be accessible to authenticated users
  res.json({ message: 'You have accessed a protected route!' });
});

Backend API Reference

The backend exposes the following API endpoints under the /api/auth prefix.

| Method | Endpoint | Description | |--------|------------------------|-------------------------------------------------------| | POST | /signup | Register a new user. | | POST | /signin | Log in an existing user. | | POST | /signout | Log out the current user. | | GET | /me | Get the profile of the currently authenticated user. | | GET | /oauth-status | Check which OAuth providers are enabled. | | GET | /google | Initiate Google OAuth login. | | GET | /google/callback | Callback URL for Google OAuth. | | GET | /github | Initiate GitHub OAuth login. | | GET | /github/callback | Callback URL for GitHub OAuth. | | POST | /set-password | Allow an OAuth user to set a password. |

Customization and Contributing

We welcome contributions and custom implementations! 💖

Customizing Styles

You can override the component's default styles by targeting the CSS classes outlined in the CUSTOMIZATION.md file. For best results, make your CSS selectors more specific than the library's.

Example: Overriding input focus color

/* Make selector more specific to win */
body .auth-container.modern .form-input:focus {
  border-color: #ff8a00;
  box-shadow: 0 0 0 3px rgba(255, 138, 0, 0.3);
}

Contributing a New Theme

Have you built a great-looking theme? We'd love to include it!

Fork the repository and create a new branch.
Add your CSS to frontend/src/components/AuthForm.css. Wrap all your styles in a unique theme class (e.g., .auth-container.my-theme).
Test your theme thoroughly in both signin and signup modes, including error states and different screen sizes.
Submit a pull request with a screenshot of your theme in action.

Reporting Issues

If you encounter a bug or have a feature request, please open an issue on our GitHub repository. Provide as much detail as possible, including:

A clear description of the issue.
Steps to reproduce it.
Any relevant error messages or console logs.
Your environment details (Node.js version, browser, etc.).

🚀 Deployment and Troubleshooting

Moving your application to a production environment requires careful configuration to ensure security and functionality.

Deployment Checklist

Set NODE_ENV: Your hosting environment must have NODE_ENV=production. This is critical for security and performance.
Configure Environment Variables:
- MONGO_URI: Your production database connection string.
- JWT_SECRET: A long, random, unique string for signing tokens.
- CORS_ORIGIN: Your exact frontend production URL (e.g., https://www.your-app.com).
- (Optional) OAuth credentials (GOOGLE_CLIENT_ID, GITHUB_CLIENT_SECRET, etc.)

Update Backend Configuration: Pass your environment variables to the createAuthBackend function.

const app = createAuthBackend({
  mongoUri: process.env.MONGO_URI,
  jwtSecret: process.env.JWT_SECRET,
  corsOrigin: process.env.CORS_ORIGIN,
  enableOAuth: true, // if using OAuth
  oauth: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      callbackURL: '/api/auth/google/callback'
    }
  }
});

Update Frontend Configuration: Set the apiUrl in your AuthProvider to point to your live backend.
```
<AuthProvider apiUrl="https://api.your-app.com/api/auth">
  {/* ... */}
</AuthProvider>
```
Configure OAuth Redirect URIs: In your Google/GitHub developer console, add your production callback URL (e.g., https://api.your-app.com/api/auth/google/callback) to the list of authorized redirect URIs.

Common Issues

"CORS Error": This means the corsOrigin in your backend config does not exactly match the URL of your frontend. Check for typos, and ensure it includes https://.
"Invalid Token" / "No Token Provided": This can happen if the frontend and backend are on different root domains (e.g., app.com and api.herokuapp.com), as browsers may block third-party cookies. To fix this, ensure both your frontend and backend are on subdomains of the same parent domain (e.g., www.app.com and api.app.com).
OAuth Login Fails with "Redirect URI Mismatch": The callback URL registered in your OAuth provider's settings does not exactly match the one your backend is configured with.
User is Logged Out on Refresh: This could mean cookies are not being set correctly. Ensure withCredentials: true is set in your frontend requests (Axios does this by default in this package) and that your CORS/domain configuration is correct.

Use Cases

Dimsee is ideal for:

🚀 Prototyping MERN applications: Quickly add authentication to your projects.
SaaS products: A solid foundation for user management.
🏢 Internal tools: Secure your internal applications with minimal effort.
🎓 Learning: A great way to see how full-stack authentication is implemented.

License

This project is licensed under the MIT License. See the LICENSE file for details.