DEV Community: vanced youtube

Background Tasks in Kotlin Multiplatform: Unifying Android WorkManager and iOS BGTaskScheduler

vanced youtube — Wed, 02 Sep 2026 15:06:49 +0000

Writing shared Kotlin code across Android and iOS is genuinely productive — until you need to schedule work that runs in the background. At that point the platforms diverge sharply, and the usual KMP approach of "write once, adapt per platform" gets uncomfortable fast.

On Android you have Jetpack WorkManager, a robust, battle-tested API backed by the OS job scheduler. It handles constraints (network, charging, idle), exponential backoff, unique work policies, and periodic tasks. On iOS you have BGTaskScheduler, Apple's tightly controlled background execution framework, which gives you roughly 30 seconds for a refresh task and zero guarantees about when it will actually run.

These two systems are not just different APIs — they represent genuinely different philosophies about how much control an app should have over when its code runs. Getting a single Kotlin interface to sit cleanly over both, without leaking platform assumptions into shared code, requires some deliberate design choices.

This is a walkthrough of KMPWorker, an open-source library we built at NeuralHeads to solve exactly this problem.

The Core Interface Problem

Before writing any Android or iOS code, the first decision was: what does a platform-agnostic task API actually look like?

The KmpWorker interface in core is the answer. It defines the contract that both AndroidKmpWorker and IOSKmpWorker implement:

interface KmpWorker {
    suspend fun enqueue(request: TaskRequest)
    suspend fun cancel(taskId: String)
    fun observe(taskId: String): Flow<TaskState>
    fun register(taskId: String, block: suspend () -> Unit)
    fun registerWithContext(taskId: String, block: suspend TaskExecutionContext.() -> Unit)
    suspend fun enqueueChain(chain: TaskChain, policy: ChainPolicy)
    // ...
}

The register / enqueue split is intentional. Handlers are registered at app startup (before enqueue ever gets called), and enqueue schedules the actual work. On iOS this matters because BGTaskScheduler requires all identifiers to be registered with the OS before applicationDidFinishLaunching returns — you cannot register a task handler lazily at the point you want to run it.

TaskState flows through Kotlin's Flow<TaskState>, covering the full lifecycle:

Scheduled → Running → Success
                    → Failed(throwable, retryCount, willRetry)
                    → Cancelled(reason)
                    → TimedOut(afterMillis)

Because this is a shared Flow, UI code in either Android or iOS (via Swift interop) can observe state changes reactively, without polling or callbacks.

How Android Maps to WorkManager

The Android implementation lives in AndroidTaskScheduler. For each TaskRequest, it constructs a OneTimeWorkRequest or PeriodicWorkRequest and delegates to WorkManager. The mapping is fairly direct for most cases.

TaskType is a sealed class:

sealed class TaskType {
    data object OneTime : TaskType()
    data class Periodic(val repeatIntervalMillis: Long) : TaskType()
    data class ExactTime(val runAtMillis: Long) : TaskType()
    data class Windowed(val earliestMillis: Long, val latestMillis: Long) : TaskType()
}

ExactTime maps to WorkManager's setInitialDelay(). This is worth calling out explicitly: WorkManager does not offer hard exact scheduling. The actual execution happens at or after the specified time, subject to battery optimizations and Doze mode. If your use case genuinely requires millisecond-precise execution, WorkManager is the wrong tool on Android regardless of any abstraction layer on top.

Windowed behaves similarly — the earliestMillis becomes the initial delay and the latestMillis is informational in the current Android implementation (WorkManager has a flex interval for PeriodicWorkRequest, but not directly for one-time tasks).

Constraints map cleanly to WorkManager's Constraints.Builder:

private fun buildWorkConstraints(kmpConstraints: Constraints): androidx.work.Constraints {
    val builder = Constraints.Builder()
        .setRequiredNetworkType(
            when {
                kmpConstraints.requiresUnmeteredNetwork -> NetworkType.UNMETERED
                kmpConstraints.requiresNonRoamingNetwork -> NetworkType.NOT_ROAMING
                kmpConstraints.requiresInternet -> NetworkType.CONNECTED
                else -> NetworkType.NOT_REQUIRED
            }
        )
        .setRequiresCharging(kmpConstraints.requiresCharging)
        .setRequiresBatteryNotLow(kmpConstraints.batteryNotLow)
        .setRequiresDeviceIdle(kmpConstraints.requiresDeviceIdle)
    // ...
    return builder.build()
}

Network constraint resolution follows a priority order: requiresUnmeteredNetwork takes precedence over requiresNonRoamingNetwork, which takes precedence over requiresInternet. Only one NetworkType can be set in WorkManager, so the library resolves the most restrictive constraint.

The actual work runs inside KmpTaskWorker, which extends CoroutineWorker. This is where retry logic, timeout enforcement, and telemetry bridging happen:

override suspend fun doWork(): Result {
    val taskId = inputData.getString(KEY_TASK_ID) ?: return Result.failure()
    // ...
    return try {
        TaskMonitor.emit(taskId, TaskState.Running())
        if (timeout != null) {
            withTimeout(timeout) { TaskRegistry.execute(taskId, ctx) }
        } else {
            TaskRegistry.execute(taskId, ctx)
        }
        TaskMonitor.emit(taskId, TaskState.Success)
        Result.success()
    } catch (e: TimeoutCancellationException) {
        TaskMonitor.emit(taskId, TaskState.TimedOut(afterMillis = elapsed))
        Result.failure()
    } catch (e: Exception) {
        val willRetry = RetryEngine.shouldRetry(retryCount, retryPolicy)
        TaskMonitor.emit(taskId, TaskState.Failed(e, retryCount, willRetry))
        if (willRetry) Result.retry() else Result.failure()
    }
}

One detail worth noting: the retry policy is serialized into WorkManager's inputData as string constants, because WorkManager's Data object only supports primitive types. The policy type, delay, and max retry count are stored as separate keys and reconstructed inside KmpTaskWorker.readRetryPolicy().

The iOS Side: What BGTaskScheduler Actually Constrains

iOS is harder. The IOSTaskScheduler uses BGTaskScheduler with two task types: BGAppRefreshTask for TaskType.OneTime, and BGProcessingTask for TaskType.Periodic.

The most important thing to understand about BGTaskScheduler — documented clearly in the repo's docs/ios-limitations.md — is that the entire scheduling decision belongs to Apple:

What your app controls	What Apple controls
Requesting a task identifier	Whether the task runs at all
Setting `earliestBeginDate`	When the task actually runs
Handling the expiration callback	How long the task gets to run

For BGAppRefreshTask, your handler gets approximately 30 seconds. Apple enforces this with an expiration handler that fires when the budget runs out. The iOS scheduler in KMPWorker registers this expiration handler and emits TaskState.TimedOut when it fires, rather than leaving the task in an indeterminate state.

The Periodic task type maps to BGProcessingTask, which typically only runs when the device is connected to power and idle. It gets a longer execution window than a refresh task, but comes with stricter system preconditions. There is currently no way to guarantee that a periodic KMPWorker task will run at a specific interval on iOS — the repeatIntervalMillis value is a hint to the system, not a contract.

The cancelByTag() implementation on iOS is a good example of where the platform diverges from Android's model. WorkManager supports cancelling by tag natively. BGTaskScheduler only supports cancellation by identifier. So IOSKmpWorker.cancelByTag() currently cancels all registered tasks, which is a broader operation than what Android's implementation does. This is called out explicitly in the source with a warning log.

If tag-level cancellation granularity matters for your use case on iOS, this is a limitation to design around.

State Broadcasting with TaskMonitor

State changes flow through TaskMonitor, a singleton that wraps a MutableSharedFlow:

private val states = MutableSharedFlow<Pair<String, TaskState>>(
    replay = 1,
    extraBufferCapacity = 64
)

The replay = 1 is important: new collectors immediately receive the last emitted state for any task, without waiting for the next emission. This means a UI screen that navigates to a task-detail view after the task has already completed will still see TaskState.Success rather than nothing.

extraBufferCapacity = 64 prevents slow collectors from back-pressuring the emitters. A background task running in KmpTaskWorker should never be blocked by a UI observer being slow to consume events.

For apps that need state to survive process termination — common for sync tasks that need to surface completion even if the user relaunched the app — there's an optional EventStore mechanism. Terminal states (Success, Cancelled, Failed with willRetry = false) are written to the store before the in-memory emit, so even if the process dies immediately after writing, the event is safely on disk. TaskMonitor.replayPendingEvents() is then called at app startup to rebroadcast any events that weren't delivered in the previous session.

Retry Engine

RetryEngine is stateless — a pure function that maps (retryCount, RetryPolicy) to a delay in milliseconds:

is RetryPolicy.Exponential -> {
    val maxDelay = Long.MAX_VALUE / 2
    val shift = retryCount.coerceIn(0, 62)
    val multiplier = 1L shl shift  // 2^shift
    if (multiplier > maxDelay / policy.initialDelayMillis.coerceAtLeast(1L)) {
        maxDelay
    } else {
        policy.initialDelayMillis * multiplier
    }
}

The overflow guard is deliberate. Without it, a long-running exponential backoff (say, 64+ retries) would overflow a Long and produce a negative delay. The implementation caps at Long.MAX_VALUE / 2 — a safe practical ceiling that prevents arithmetic errors without complicating the calling code.

The three available policies:

RetryPolicy.None                                  // no retry
RetryPolicy.Linear(delayMillis = 5_000)           // fixed 5s between attempts
RetryPolicy.Exponential(
    initialDelayMillis = 5_000,                   // attempt 1: 5s
    maxRetries = 5                                // attempt 2: 10s, 3: 20s, 4: 40s, 5: 80s
)

Task Chains and Step Persistence

For multi-step workflows where each step must complete before the next begins, TaskChain provides a sequenced execution model. The chain executor (TaskChainExecutor) observes TaskMonitor.observeAll() and advances to the next step on success.

What makes this non-trivial is crash safety. Before enqueueing step n+1, the chain executor calls chainRepository.updateStep(chain.id, nextStep, "RUNNING"). This means if the process is killed between step completions, restorePendingChains() at the next launch will resume from the last committed step rather than restarting from step 0.

Step task IDs are namespaced under the chain ID (${chain.id}:step:${index}) to avoid collisions with independently scheduled tasks.

The builder DSL makes common chains readable:

kmpWorker.chain("onboarding", policy = ChainPolicy.REPLACE) {
    beginWith("fetch-profile")
    then("upload-avatar") {
        constraints = Constraints(requiresInternet = true)
    }
    then("notify-server") {
        retryPolicy = RetryPolicy.Exponential(5_000, 3)
    }
}

ChainPolicy.REPLACE cancels any existing chain with the same ID before starting a new one. ChainPolicy.KEEP skips enqueue if a chain with that ID is already running. ChainPolicy.ALLOW_DUPLICATE (the default) always enqueues, which is useful for chains where concurrent executions of different "runs" are intentional.

What's Experimental and What's Stable

The DAG (Directed Acyclic Graph) execution API — which allows independent nodes to run in parallel while respecting declared dependencies — is marked @OptIn(ExperimentalKmpWorkerApi::class). This means the API surface may change between releases. The chain API and the core KmpWorker interface are stable.

The transfer module (kmpworker-transfer) uses HttpURLConnection on Android and NSURLSession on iOS for resumable background downloads and uploads, without pulling in Ktor. This avoids adding a heavyweight dependency just for HTTP, but it also means the transfer module lacks Ktor's interceptor model and authentication abstractions. If your use case involves complex auth flows or middleware, you'd likely want to layer your own HTTP client on top of KMPWorker's task scheduling rather than using the transfer module directly.

Getting Started

Add the umbrella artifact or pick specific modules:

// shared module build.gradle.kts
commonMain.dependencies {
    implementation("io.neuralheads.kmpworker:kmpworker-core:0.1.0")
}
androidMain.dependencies {
    implementation("io.neuralheads.kmpworker:kmpworker-android:0.1.0")
}
iosMain.dependencies {
    implementation("io.neuralheads.kmpworker:kmpworker-ios:0.1.0")
}

Android initialization is handled automatically via KmpWorkerInitializer, which uses the App Startup library to wire up the WorkManager factory without requiring any Application subclass code.

iOS requires explicit initialization in AppDelegate before the app finishes launching:

let kmpWorker = IOSKmpWorker()

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    kmpWorker.register(taskId: "sync") { /* your work */ }
    kmpWorker.initialize()
    return true
}

The full module reference and documentation are in the GitHub repository.

Where This Goes Next

The core scheduling and chain execution is stable. The areas still under active development include the DAG executor (experimental), the Compose Multiplatform live inspector (kmpworker-inspector), and expanding the transfer module's error handling. The next article in this series covers the offline queue and persistence architecture — specifically how SQLDelight is used to ensure tasks survive app termination and network disconnections.

If you're building a KMP app that needs reliable background work across both platforms, KMPWorker gives you a starting point that handles the platform-specific wiring so your shared code does not have to.

KMPWorker is published under the Apache 2.0 license. Source is available at github.com/neuralheads/kmpworker.

The Utility-First Paradox: Structuring Massive UI Kits with Tailwind CSS and React 19

vanced youtube — Wed, 15 Apr 2026 18:56:14 +0000

Let’s be honest: Tailwind CSS is the "Wild West" of frontend development. It’s incredibly fast to iterate, but if you don't have a systemic approach to architecture, a project the size of ProofMatcher—with nine distinct premium templates and hundreds of components—quickly descends into a "class soup" nightmare.

Most developers start by slapping utilities on every div until it looks right. That works for a single landing page. But when you’re building a high-fidelity marketplace using React 19, Vite, and a decoupled Django backend, you need a styling architecture that scales without bloating your bundle or making your components unreadable.

Here is how we structured the styling engine for ProofMatcher to ensure performance and maintainability at scale.

1. Design Tokens: The "Single Source of Truth"

The biggest mistake you can make with Tailwind is relying on ad-hoc values (e.g., text-[#c6f91f] or p-[1.45rem]). In a massive UI kit, these arbitrary values are technical debt waiting to happen.

We treat our tailwind.config.js as the "Design System Bible." We don't just define colors; we define rhythm. Every spacing value, blur intensity, and gradient angle is tokenized. For instance, in our Neural Core template, we don't use a random cyan. We use theme('colors.brand.primary').

// tailwind.config.js snippet
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          neon: '#c6f91f',
          surface: '#05080A',
          border: 'rgba(255, 255, 255, 0.1)',
        },
      },
      backdropBlur: {
        'glass': '12px',
      },
      animation: {
        'shimmer': 'shimmer 1.5s infinite',
      }
    }
  }
}

By strictly adhering to tokens, we can change the entire "vibe" of a template by updating one config file, rather than hunting through 50 .tsx files.

2. Component Abstraction vs. Class Bloat

The "Tailwind makes code messy" argument is usually a symptom of poor component abstraction. If your React component has 40 classes on a single div, you probably haven't broken the component down far enough.

In React 19, we lean heavily into Atomic Components. Instead of styling a button every time, we build a BeamButton or a GoldBuyButton. We use the tailwind-merge and clsx pattern to handle dynamic class injection without the dreaded "class name collision" bug.

import { twMerge } from 'tailwind-merge';
import { clsx, type ClassValue } from 'clsx';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// Usage in our marketplace
<button className={cn(
  "px-6 py-3 rounded-lg transition-all duration-300",
  isPro ? "bg-brand-neon text-black" : "bg-white/5 text-white",
  className
)}>
  {children}
</button>

This pattern allows us to keep the component logic separate from the "styling soup," while still maintaining the efficiency of Tailwind's JIT (Just-In-Time) compiler.

3. The Death of `@apply`

If you are using @apply to create "component classes" in your CSS files, you are likely doing it wrong. While it looks cleaner, you lose the primary benefit of Tailwind: the ability to see exactly what a component looks like by looking at its markup. More importantly, @apply balloons your final CSS bundle because it duplicates the actual CSS properties rather than reusing the atomic utility classes.

At ProofMatcher, our index.css is almost empty. We handle 99% of our styles via React props and utility classes. This ensures that Vite can perform optimal tree-shaking, only shipping the CSS that is actually active in the user's viewport.

4. Handling Transitions and State in React 19

React 19’s new useTransition and useActionState hooks are a game-changer for UI feedback. We coordinate these states with Tailwind's group and peer utilities.

For example, our CheckoutPage uses "Loading States" that are entirely CSS-driven. When a Django DRF action is pending, we toggle a single is-pending class on a parent container, and all child "skeleton" elements automatically trigger their shimmer animations via the group-is-pending:animate-shimmer utility. This keeps the JavaScript layer focused on data and the styling layer focused on visuals.

5. Decoupled Styling: The Django Context

When working with a decoupled Django backend, you often need to share "status colors" or "brand themes" across the API. We achieve this by serving Design Tokens as a JSON endpoint from Django, which we then inject into our CSS via CSS Variables.

Tailwind handles these variables beautifully:
bg-[var(--user-theme-color)]

This allows us to support "Dynamic Branding" for our enterprise clients. The backend tracks the brand color; the frontend renders it with Tailwind's performance.

6. Performance: The 60fps Standard

A "massive" UI kit often suffers from layout shifts and janky animations. We use Tailwind primarily for layout and static styling, but we delegate complex or high-frequency animations (like the 3D orbit gallery in our Creative Agency template) to GSAP or Framer Motion, controlled via React refs.

The division of labor is clear:

Tailwind: Layout, colors, spacing, and hover states.
GSAP: Narrative animations and coordinate-based movements.
Vite: Aggressive purging and chunking.

By following this hierarchy, our marketplace maintains a 95+ performance score on mobile, even with high-fidelity 3D assets running in the background.

Conclusion: See the Blueprint

Structuring a massive UI kit isn't about avoiding utility classes; it's about systematizing them. It's about building a language where neon means something specific across 500 components.

If you want to see exactly how we handled the "class soup" problem in a real production environment, you don't need to take my word for it. We’ve open-sourced our Neural Core Interface—the same tech stack we use to build our premium marketplace.

Visit proofmatcher.com and download the Free UI Kit. Dig into the code, check out the tailwind.config.js, and see how we’ve utilized React 19 and Vite to create a lightning-fast, highly-maintainable styling system. Stop writing messy CSS and start building systems.

Why We Killed CRA: Building a High-Performance Marketplace with React 19 + Vite + Django

vanced youtube — Sun, 12 Apr 2026 13:58:49 +0000

Let me be real: if you're still using create-react-app for production apps in 2024, you're fighting your own tooling.

At ProofMatcher, we run a marketplace for premium website templates — think animated, interactive modern web templates with live previews. Our stack? React 19, Vite, Tailwind, and Django REST Framework.

Here's why we ditched CRA and what we learned shipping this to production.

The Problem: CRA Can't Keep Up

When you're building a template marketplace, you're basically shipping a gallery of mini-apps. Each template has:

Live previews (often with Three.js or GSAP)
Custom animations
Heavy asset loading
SEO requirements

CRA's dev server started choking around 20+ templates. Cold starts took 30+ seconds. HMR felt random. Our team was spending more time waiting than coding.

Why Vite Won

Vite's dev server uses ESM natively. No more bundling everything upfront. Your browser fetches modules as needed.

The difference is night and day:

Cold starts: ~1s vs 30s
HMR updates: Instant vs "is it working?"
Memory usage: ~500MB vs 2GB+

Here's our base config:

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: {
      '/api': 'http://localhost:8000'
    }
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          three: ['three'],
          ui: ['framer-motion', 'lucide-react']
        }
      }
    }
  }
})

React 19 in Production

Yes, we're running React 19. No, it's not "unstable." The React team's been releasing canary builds for ages, and the Vite plugin handles it beautifully.

The real win? React Server Components aren't mandatory. You can use the new features (like Actions) without buying into the full RSC architecture.

Our async setup with Django:

// Using React 19's use() with Suspense
async function fetchTemplate(id) {
  const res = await fetch(`/api/templates/${id}/`)
  return res.json()
}

function TemplatePreview({ id }) {
  const template = use(fetchTemplate(id))

  return (
    <div>
      <h1>{template.name}</h1>
      <iframe src={template.previewUrl} />
    </div>
  )
}

// Wrap with Suspense where used
<Suspense fallback={<TemplateSkeleton />}>
  <TemplatePreview id={123} />
</Suspense>

Django + Vite: The Proxy Magic

We keep frontend and backend completely separate. Django handles:

Authentication (JWT via SimpleJWT)
Database models
Stripe webhooks
File uploads (S3 presigned URLs)

Vite proxies API requests during development, so no CORS issues:

// In Django settings.py
CORS_ALLOWED_ORIGINS = [
    "http://localhost:5173",  # Vite dev server
    "https://proofmatcher.com",
]

# And for production:
STATICFILES_DIRS = [
    BASE_DIR / "frontend-dist",  # Built Vite assets
]

Performance Wins That Matter

1. Chunking Strategy

We manually split Three.js from our main bundle. Users don't pay for 3D unless they view a 3D template.

2. Image Optimization

Using Vite's built-in image handling:

import templateImage from './assets/template.jpg?w=800&format=webp'
// Generates multiple sizes, webp format

3. CSS That Doesn't Block

Tailwind + Vite's JIT mode means CSS updates are instant. No more PostCSS rebuild delays.

The Iframe Preview Solution

This was our trickiest problem: how to preview templates without style collisions.

Solution: Each preview runs in a sandboxed iframe:

<!-- Template preview component -->
<div class="preview-container">
  <iframe
    sandbox="allow-scripts allow-same-origin"
    src={`/template-previews/${templateId}/`}
  />
</div>

Vite builds these previews as separate mini-apps in /public. Zero runtime cost for the main app.

SEO Without SSR

We get this question a lot: "How do you handle SEO without Next.js?"

Honestly? Good old <meta> tags and smart URL design. Django pre-renders critical pages (homepage, categories), and React takes over after load.

Our SEOHead component:

function SEOHead({ title, description, image }) {
  return (
    <>
      <title>{title} | ProofMatcher</title>
      <meta name="description" content={description} />
      <meta property="og:image" content={image} />
      <link rel="canonical" href={window.location.href} />
    </>
  )
}

For a marketplace, Google cares more about page speed and user experience than perfect SSR. Our Lighthouse scores:

Performance: 98
SEO: 100
Accessibility: 97

Would We Do It Again?

Absolutely. Our developer experience improved dramatically:

Metric	CRA	Vite
Dev server start	30s	1.2s
HMR update	2-5s	<100ms
Production build	4min	45s
Bundle size (homepage)	450KB	180KB

The team ships features faster. Our templates load quicker. Users stay longer.

Getting Started Yourself

If you want to try this stack:

# Frontend
npx create-vite@latest myapp --template react
cd myapp
npm install

# Backend
pip install django djangorestframework django-cors-headers
django-admin startproject backend .

Check out Vite's docs and Django REST Framework. Both have fantastic communities.

Wrapping Up

CRA served its purpose. But for modern apps with complex UIs, Vite is just better. Faster dev server, smaller bundles, better DX.

We're open sourcing our base template if you want to see the exact setup. It includes:

React 19 + Vite config
Django API setup
Three.js chunking
Iframe preview system

What's your stack look like? Still on CRA or moved to something else?