X-Framework Documentation

# Install the X CLI globally
npm i -g @bluelibs/x

# Initialize project (follow the interactive prompts)
x

# Navigate to project directory
cd project

# Generate Blueprint code
npm run blueprint:generate

# Start the API
npm run start:api

# Start the Admin UI
npm run start:admin

- src
  - startup
    - kernel.ts
    - index.ts
    - styles.scss # Main entry point for styles
  - bundles
    - UIAppBundle
      - routes.tsx # Imports all routes
      - UIAppBundle.tsx
      - collections # CRUD module interactions
        - index.ts
        - {CollectionName}.collection.ts
      - components
        - index.ts
        - {ComponentName}.tsx
      - overrides # Component overrides for other bundles
        - {ComponentName}.tsx
      - pages
        - routes.tsx
        - {PageName}
          - routes.tsx
          - {PageName}.tsx
          - components # Page-specific components
      - services
        - {Name}.service.ts
      - styles
        - style.scss

const guardian = useGuardian();
const {
  initialised,      // True after first page load, token reading, and user fetching
  isLoggedIn,       // True if user is authenticated
  hasInvalidToken,  // True if stored token expired during initialization
  fetchingUserData, // True while the me() query is in progress
  user,             // The current user object
} = guardian.state;

// Check for specific roles
const isAdmin = guardian.hasRole(Roles.ADMIN);

import * as passport from "passport";
import { Strategy as FacebookStrategy } from "passport-facebook";
import { PassportAuthenticator } from "../models/PassportAuthenticator";

export class FacebookAuthenticator extends PassportAuthenticator {
  createStrategy() {
    return new FacebookStrategy(
      {
        clientID: "XXX",
        clientSecret: "XXX",
        callbackURL: "http://localhost:4000/auth/facebook/callback",
      },
      async (accesstoken, refreshToken, profile, done) => {
        try {
          const { isNew, user } = await this.findOrCreate(profile.id);
          if (isNew) {
            this.securityService.updateUser(user._id, { /* update data */ });
          }
          done(null, user);
        } catch (err) {
          done(err);
        }
      }
    );
  }

  route() {
    // Redirect to provider
    this.app.get("/auth/facebook", passport.authenticate(this.name));

    // Handle callback
    this.get(
      "/auth/facebook/callback",
      {},
      async (err, user, req, res, next) => {
        const token = await this.getToken(user._id);
        res.redirect(`https://uihost.com/facebook/success?token=${token}`);
      }
    );
  }
}

// Registration in AppBundle
class AppBundle extends Bundle {
  async init() {
    const passportService = this.container.get(PassportService);
    passportService.register(FacebookAuthenticator);
  }
}

import { SecurityService } from "@bluelibs/security-bundle";
import { PasswordService } from "@bluelibs/password-bundle";

const securityService = container.get(SecurityService);
const passwordService = container.get(PasswordService);

// 1. Create user and attach password data
const userId = await securityService.createUser();
await passwordService.attach(userId, {
  username: "USERNAME",
  email: "USERNAME@MAIL.COM",
  password: "PASSWORD",
  isEmailVerified: false,
});

// 2. Find userId by username
const userId = await passwordService.findUserIdByUsername("username");

// 3. Validate password (tracks failed attempts)
const isValid = await passwordService.isPasswordValid(userId, "PASSWORD");

// 4. Validate password without triggering account lock/cooldown
const isValidBypass = await passwordService.isPasswordValid(userId, "PASSWORD", {
  failedAuthenticationAttemptsProcessing: false,
});

// Generate token to be sent via email
const token = await passwordService.createTokenForPasswordReset(userId);

// Verify the token is still valid
const isTokenValid = await passwordService.isResetPasswordTokenValid(userId, token);

// Reset the password
await passwordService.resetPassword(userId, token, "NEW_PASSWORD");