Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xreatlabs.space/llms.txt

Use this file to discover all available pages before exploring further.

​
Building from Source

Complete guide to building NexAuth from source code for development and contribution.

​
Prerequisites

​
Repository Setup

1

Clone Repository

Clone the NexAuth repository from GitHub.
git clone https://github.com/XreatLabs/NexAuth.git
cd NexAuth
2

Choose Branch

Select the branch you want to build.
# Development branch (latest features)
git checkout develop

# Stable release branch
git checkout main

# Specific version
git checkout tags/v1.0.0
3

Configure Build

Configure build properties if needed.
# Edit build.gradle.kts or pom.xml
# Customize version, dependencies, etc.

​
Building with Gradle

​
Basic Build

# Build all modules
./gradlew build

# Build without tests
./gradlew build -x test

# Build specific module
./gradlew :Plugin:build

# Clean and build
./gradlew clean build

​
Build Outputs

Build artifacts are located in: 
# Universal plugin (works on both Velocity and Paper/Purpur)
Plugin/build/libs/NexAuth.jar

# API jar
API/build/libs/NexAuth-API-x.x.x.jar
NexAuth produces a single universal JAR that works on both Velocity proxies and Paper/Purpur servers - no platform-specific builds needed.

​
Development Build

# Build with dependencies and sources
./gradlew build shadowJar

# Output includes:
# - Standard jar
# - Shadow jar (with dependencies)
# - Sources jar
# - Javadoc jar

​
Building with Maven

​
Basic Build

# Build all modules
mvn clean install

# Build without tests
mvn clean install -DskipTests

# Build specific module
mvn clean install -pl Plugin

# Package only
mvn clean package

​
Build Outputs

# Universal plugin (works on both Velocity and Paper/Purpur)
Plugin/target/NexAuth.jar

# API jar
API/target/NexAuth-API-x.x.x.jar
NexAuth produces a single universal JAR that works on both Velocity proxies and Paper/Purpur servers - no platform-specific builds needed.

​
IDE Setup

​
IntelliJ IDEA

1

Import Project

Open IntelliJ and select “Import Project”Choose the NexAuth directory
2

Select Build System

Choose Gradle or Maven as the build systemLet IntelliJ auto-import dependencies
3

Configure SDK

Set Project SDK to Java 17+Set Language Level to 17
4

Enable Annotation Processing

Settings → Build, Execution, Deployment → Compiler → Annotation ProcessorsEnable “Enable annotation processing”
5

Run Configuration

Create run configurations for testing:
  • Velocity: Run Velocity proxy
  • Paper: Run Paper server
  • Tests: Run unit tests

​
VS Code

1

Install Extensions

Install these VS Code extensions:
  • Extension Pack for Java
  • Gradle for Java
  • Maven for Java
  • Code Spell Checker
2

Open Project

Open the NexAuth directory in VS Code
3

Import Build

VS Code will automatically detect Gradle/Maven and import dependencies
4

Configure Settings

Ensure Java 17+ is configured in settings.json

​
Testing

​
Unit Tests

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "com.nexauth.AuthTest"

# Run with coverage
./gradlew test jacocoTestReport

​
Integration Tests

# Run integration tests
./gradlew integrationTest

# Run specific integration test
./gradlew integrationTest --tests "com.nexauth.DatabaseIntegrationTest"

​
Test Database Setup

Configure test database in src/test/resources/test-config.conf: 
database {
    type="h2"  # Use H2 for testing
    path="mem:testdb"
}

​
Development Workflow

​
Making Changes

1

Create Feature Branch

git checkout -b feature/your-feature-name
2

Make Changes

Edit source files in your IDEMake sure to follow code style guidelines
3

Build and Test

# Build changes
./gradlew build

# Run tests
./gradlew test
4

Commit Changes

git add .
git commit -m "feat: add your feature description"
5

Push and PR

git push origin feature/your-feature-name
# Create Pull Request on GitHub

​
Debugging

​
Debug Server Startup

# Build with debug enabled
./gradlew build -Pdebug

# Run with debug logging
# Add -Dnexauth.debug=3 to server startup

​
Debug in IDE

  1. Set breakpoints in your code
  2. Start server in debug mode
  3. Attach debugger to server process
  4. Debug code execution

​
Continuous Integration

​
GitHub Actions

NexAuth uses GitHub Actions for CI/CD: 
# .github/workflows/build.yml
name: Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17'
      - name: Build with Gradle
        run: ./gradlew build
      - name: Run tests
        run: ./gradlew test

​
Local CI Testing

# Run CI pipeline locally
act push  # Using act for local GitHub Actions

# Or run build script
./scripts/ci-build.sh

​
Release Building

​
Build Release Artifacts

# Build release version
./gradlew clean build release

# Generate release notes
./scripts/generate-release-notes.sh

# Create GitHub release
gh release create v1.0.0 \
  Plugin/build/libs/*.jar \
  --notes-file RELEASE_NOTES.md

​
Version Management

# Update version in build files
./gradlew setVersion -PnewVersion=1.0.0

# Commit version change
git commit -am "chore: bump version to 1.0.0"

# Create version tag
git tag v1.0.0
git push origin v1.0.0

​
Troubleshooting

Solution:
# Clean and rebuild
./gradlew clean build --refresh-dependencies

# Clear Gradle cache
rm -rf ~/.gradle/caches/
./gradlew build
Possible causes:
  1. Database not configured
  2. Port conflicts
  3. Missing test resources
Solutions:
# Use H2 for testing
# Configure in test-config.yml

# Run tests in order
./gradlew test --tests "*Test*"

# Check test logs
cat build/reports/tests/test/index.html
Solution:
# Refresh Gradle project
./gradlew --refresh-dependencies

# Reimport project in IDE
# IntelliJ: File → Invalidate Caches → Invalidate and Restart

​
Best Practices

​
Next Steps

Contributing Guidelines

Learn how to contribute to NexAuth development.