Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18 or higher required

npm

Or any compatible Node package manager (pnpm, yarn)
Check your Node version with node --version. If you need to install or update Node.js, visit nodejs.org.

​
Quick setup

1

Clone the repository

Clone the Atomix QRGen repository from GitHub:
git clone https://github.com/Ephistopheles/atomix-qrgen.git
cd atomix-qrgen
The repository includes all source code, dependencies configuration, and build scripts needed to run the project.
2

Install dependencies

Install the required npm packages:
npm install
This installs:
  • astro (5.17.1) - Static site generator
  • preact (10.28.3) - UI component library
  • tailwindcss (4.1.18) - CSS framework
  • qr-code-styling (1.9.2) - QR code generation
  • @astrojs/preact (4.1.3) - Astro integration for Preact
Using pnpm or yarn? They work too! Just run pnpm install or yarn install instead.
3

Start the development server

Launch the local development server:
npm run dev
You should see output similar to:
🚀 astro v5.17.1 started in 150ms

┃ Local    http://localhost:4321/
┃ Network  use --host to expose
Open http://localhost:4321 in your browser to see the app running.
The dev server includes hot module replacement (HMR), so changes to your code will automatically refresh the browser.
4

Start generating QR codes

The app is now running locally! Try generating a QR code:
  1. Select a QR type (e.g., URL / Link)
  2. Enter your data
  3. See the real-time preview
  4. Download or print your QR code

​
Available commands

Atomix QRGen includes several npm scripts for development and production:
CommandDescription
npm run devStart the local development server at http://localhost:4321
npm run buildBuild the optimized production site to ./dist
npm run previewPreview the production build locally before deployment
npm run astroRun Astro CLI commands directly

​
Development workflow

# Start development server
npm run dev

# Make your changes...
# The browser auto-refreshes with HMR

# Build for production
npm run build

# Preview production build
npm run preview

​
Project structure

Understanding the codebase structure helps you navigate and modify the project: 
atomix-qrgen/
├── src/
│   ├── pages/
│   │   └── index.astro              # Main entry point
│   ├── layouts/
│   │   └── RootLayout.astro         # Global layout and meta tags
│   ├── components/
│   │   ├── qr-code-app/
│   │   │   ├── app/
│   │   │   │   └── qr-gen-app.tsx   # Main app logic and state
│   │   │   └── cards/
│   │   │       ├── qr-types/        # QR type selector
│   │   │       ├── content-input-card/  # Dynamic form container
│   │   │       └── qr-preview/      # QR display & download
│   │   └── forms/
│   │       ├── url/                 # URL form component
│   │       ├── text/                # Text form component
│   │       ├── wifi/                # WiFi form component
│   │       ├── v-card-form/         # vCard form component
│   │       ├── event-form/          # Event form component
│   │       ├── payment-form/        # Payment form component
│   │       └── shared/              # Reusable form inputs
│   ├── domain/
│   │   ├── types/
│   │   │   └── qr.ts                # TypeScript type definitions
│   │   ├── encoders/
│   │   │   └── encoders.ts          # QR data format encoders
│   │   ├── validation/
│   │   │   └── validators.ts        # Input validation logic
│   │   ├── form/
│   │   │   └── form-registry.ts     # Form component registry
│   │   ├── hooks/
│   │   │   └── use-form-data.ts     # Form state management
│   │   └── ui/
│   │       └── toast.ts             # Toast notifications
│   └── styles/
│       └── global.css               # Tailwind config and utilities
├── public/                          # Static assets
├── astro.config.mjs                 # Astro configuration
├── package.json                     # Dependencies and scripts
└── tsconfig.json                    # TypeScript configuration
The app uses a component-based architecture:
  • Astro components (.astro) - Static pages and layouts
  • Preact components (.tsx) - Interactive UI with client-side state
  • Domain logic (domain/) - Encoders, validators, types (framework-agnostic)

​
Configuration

​
Astro config

The Astro configuration enables Preact integration and Tailwind CSS: 
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';
import preact from '@astrojs/preact';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()]
  },
  integrations: [preact()]
});

​
TypeScript config

TypeScript is configured for strict type checking: 
// tsconfig.json
{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}

​
Building for production

When you’re ready to deploy:
1

Build the static site

npm run build
This creates an optimized production build in the ./dist directory with:
  • Minified JavaScript and CSS
  • Optimized images
  • Pre-rendered HTML pages
2

Preview the build

Test the production build locally:
npm run preview
This serves the ./dist folder at http://localhost:4321 to verify everything works.
3

Deploy

Deploy the ./dist folder to any static hosting service:
  • Vercel: Connect your GitHub repo for automatic deployments
  • Netlify: Drag and drop the dist folder or use Git integration
  • GitHub Pages: Push to gh-pages branch
  • Cloudflare Pages: Connect repository or upload directly
Atomix QRGen is a static site with no backend requirements, making deployment simple and cost-effective.

​
Development tips

The dev server automatically refreshes when you save changes. For Preact components, state is preserved across refreshes when possible.
To add a new QR format:
  1. Define the type in src/domain/types/qr.ts
  2. Create an encoder in src/domain/encoders/encoders.ts
  3. Add validation in src/domain/validation/validators.ts
  4. Build the form component in src/components/forms/
  5. Register in src/domain/form/form-registry.ts
  6. Add to the type selector in card-qr-type.tsx
Modify QR code styling in card-qr-preview.tsx:27-33:
qr.current = new QRCodeStyling({
  width: 280,
  height: 280,
  dotsOptions: { type: "rounded", color: "#000" },
  backgroundOptions: { color: "#ffffff" },
  // Add image, corner styling, etc.
});
Atomix QRGen works in all modern browsers:
  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+
The qr-code-styling library handles browser differences automatically.

​
Troubleshooting

Port already in use? If port 4321 is occupied, Astro will automatically try the next available port. Check the terminal output for the actual port.
Build errors? Ensure you’re using Node.js 18+ and all dependencies are installed. Try deleting node_modules and package-lock.json, then run npm install again.

​
Next steps

Quickstart

Learn how to use the app to generate QR codes

QR types

Explore all supported QR code formats

API reference

Deep dive into encoders and validators

Contributing

Contribute to the project on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us