Quick Start

Prerequisites

Requirement	Version
Java	17 or higher
Node.js	20 or higher
pnpm	Latest

Method 1: Create a Project with create-q

The recommended approach when starting a new project from scratch.

Step 1: Generate the project

npm create @softminds/q@1.0.0-SNAPSHOT

Step 2: Answer the interactive prompts

Q-Framework Project Generator v1.0.0-SNAPSHOT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

? Project name: my-app
? Group ID: com.example
? Artifact ID: my-app
? Description: My Q-Framework Application
? Client App Key: app
? Package name: com.example.myapp

── Advanced settings ──────────────────────────────
? Java version: 17
? Spring Boot version: 3.3.0
? Database: H2 (development)
? Include sample entity: Yes

Generating project...
✓ Backend project created
✓ Frontend project created
✓ Sample entity created

Project generated at: ./my-app

Saving default values

Store your frequently used settings in ~/.qframework/default-values/create-q to apply them automatically on future projects.

# ~/.qframework/default-values/create-q
groupId: com.example
javaVersion: 17
database: postgresql
clientAppKey: app

Step 3: Run the project

cd my-app
./start.sh

This starts both the backend (http://localhost:8080) and frontend (http://localhost:3000) simultaneously.

---

Method 2: Library Import (Existing Project)

Add Q-Framework capabilities to an existing Spring Boot project.

Step 1: Add dependencies

build.gradle:

dependencies {
    implementation platform('net.softminds.qframework:q-spring-boot-bom:1.0.0-SNAPSHOT')
    implementation 'net.softminds.qframework:q-spring-boot-starter:1.0.0-SNAPSHOT'
    implementation 'net.softminds.qframework:q-spring-boot-jpa:1.0.0-SNAPSHOT'
    annotationProcessor 'net.softminds.qframework:q-apt:1.0.0-SNAPSHOT'

    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'
}

Maven (pom.xml):

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>net.softminds.qframework</groupId>
            <artifactId>q-spring-boot-bom</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>net.softminds.qframework</groupId>
        <artifactId>q-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>net.softminds.qframework</groupId>
        <artifactId>q-spring-boot-jpa</artifactId>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>net.softminds.qframework</groupId>
                        <artifactId>q-apt</artifactId>
                        <version>1.0.0-SNAPSHOT</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

Step 2: No additional backend configuration needed

Auto-configuration is complete once the library is added. No additional application.yml settings are required.

Auto-configuration

The q-spring-boot module provides Spring Boot Auto-configuration. Entity and component declarations are all you need to get started.

Step 3: Add the frontend module

Set up a Nuxt 3 project and add @softminds/q-nuxt:

pnpm

pnpm add @softminds/q-nuxt

npm

npm install @softminds/q-nuxt

Then extend it in nuxt.config.ts:

export default defineNuxtConfig({
  extends: ['@softminds/q-nuxt'],
})

That's it. No additional configuration required. Q-Framework UI components are available globally once the module is loaded.

---

Creating Your First Entity

Write the entity class

package com.example.myapp.domain;

import net.softminds.qframework.context.annotations.entity.QfEntity;
import net.softminds.qframework.context.annotations.attribute.*;
import net.softminds.qframework.context.annotations.attribute.elements.QfRequiredOn;
import net.softminds.qframework.context.annotations.elements.QfI18n;
import net.softminds.qframework.context.annotations.elements.QfI18nText;

@QfEntity(
    appKey = "app",
    name = @QfI18n(
        defaultMessage = "Product",
        texts = { @QfI18nText(locale = "ko", message = "상품") }
    ),
    capabilityKey = "product-management",
    deletePolicy = @QfCrudPolicy(enabled = true)
)
public class ProductEntity {

    @QfListAttribute(sortable = true)
    @QfDetailAttribute
    @QfCreateAttribute(requiredOn = @QfRequiredOn(always = true))
    @QfUpdateAttribute(requiredOn = @QfRequiredOn(always = true))
    @QfDisplayLabel(text = "Product Name")
    private String name;

    @QfListAttribute
    @QfDetailAttribute
    @QfCreateAttribute
    @QfUpdateAttribute
    @QfDisplayLabel(text = "Price")
    private Integer price;

    @QfDetailAttribute
    @QfCreateAttribute
    @QfUpdateAttribute
    @QfControlType(QfControlType.Type.textarea)
    @QfDisplayLabel(text = "Description")
    private String description;
}

Build and run

./gradlew build
./gradlew bootRun

Verify generated APIs

Once built, the following APIs are automatically available:

GET    /api/app/products          # List with pagination
GET    /api/app/products/{id}     # Detail
POST   /api/app/products          # Create
PUT    /api/app/products/{id}     # Update
DELETE /api/app/products/{id}     # Delete
GET    /api/app/products/excel/download  # Excel export
POST   /api/app/products/excel/upload    # Excel import

Swagger UI: http://localhost:8080/swagger-ui.html

Frontend integration

Use the auto-generated UI components in your Vue/Nuxt frontend:

<template>
  <!-- Q-Framework UI component: auto-renders list/detail/create/update -->
  <QfEntityView
    client-app="app"
    entity="product"
  />
</template>

<script setup>
import { QfEntityView } from '@softminds/q-vue'
</script>

---

Next Steps

• Entity Definition — Configure more complex entities
• Validation — Detailed validation rule setup
• Capability / Access Control — Configure access control
• Core Concepts — Understand how it all works