Ux Native Cli Laravel Package

Product Decisions This Supports

• Cross-platform mobile development acceleration: Enables Symfony teams to scaffold and build Hotwire Native (Android/iOS) shells directly from PHP, reducing reliance on separate native toolchains (Xcode/Gradle) during early-stage development. native:init generates both apps from a single native.yaml source of truth, and as of v0.5.0 native:update:config re-injects that file between markers — URL, app name, icon, and top bar — without clobbering generated project code. native:build now runs this sync automatically before compiling, so config drift stops being a class of bug rather than a thing to remember.
• Hybrid app roadmap: Supports a progressive enhancement strategy — web app → native wrapper → offline-capable app with push-driven re-engagement. Offline mode and path configuration (tabs, modals) mean the native shell mirrors real navigation architecture, and v0.5.0 extends that control to the top bar (top_bar driven from Symfony path rules on both platforms), so chrome and IA are decided in PHP rather than per-platform.
• Engagement / retention feature decisions: With Firebase/APNs support, a notification-token bridge, and tap-to-deep-link handling (app open or closed), push notifications are in scope. v0.5.0 adds a NotificationTrait for Live Components, which turns "user gets a notification and lands on the right screen with the right state" into a few lines of PHP — pushing this from a spike into a shippable milestone.
• Monetization and data-capture decisions (new in v0.5.0): The AdMob bridge (--admob) and barcode scanner bridge (--barcode-scanner, with a ScanQRTrait) move two roadmap conversations from "requires a native module project" to "a flag plus a bridge." Concretely: ad-supported tiers become testable, and inventory/asset-tracking or check-in flows become viable for field-ops and internal-tool products.
• Brand and release hygiene: Icons are now generated for iOS and Android from native.icon, making app-store-style polish a config change instead of a design-to-dev handoff. Combined with the top bar, "does it look like our product?" stops being a reason to defer stakeholder demos.
• Build vs. buy: Avoids reinventing native CLI tooling while staying inside Symfony. v0.3.0 added iOS development-team signing for real devices; v0.5.0 removes another maintenance tax by serving bridge Stimulus controllers via Asset Mapper (@akyos/ux-native-cli) instead of copying them into the project — upgrades no longer mean re-copying vendored JS. Pair with the sibling package akyos/native-push for server-side sending rather than building a notification backend.
• Use cases:
  • Prototyping: Test UI/UX flows on real devices and simulators without native dev expertise.
  • Internal tools: Admin dashboards, IoT control panels, field-ops apps — now with push alerts, offline tolerance, and barcode capture.
  • Customer engagement pilots: Transactional or re-engagement notifications for a limited-distribution app before committing to store submission.
  • Ad-supported / monetization experiments: Validate whether ads belong in the product before funding a native build.
  • Cross-team collaboration: Standardized build pipelines bridging PHP backend teams and native devs.
  • CI/CD integration: Automated native builds (--platform=android --no-install) for pipeline artifacts.

When to Consider This Package

• Adopt if:

  • Your team uses Symfony + Hotwire Native and needs CLI-driven native builds without manual Xcode/Gradle setup.
  • You need push notifications (Firebase/APNs) with deep-linking and are willing to adopt akyos/native-push for the server side.
  • Your roadmap includes barcode/QR scanning or in-app advertising — v0.5.0 ships bridges and a ScanQRTrait, and both are opt-in flags rather than forks.
  • You want real-device iOS deployment without hand-managing provisioning profiles (development signing only).
  • You value config-as-source-of-truth: native:update:config plus the automatic pre-build sync means native.yaml genuinely drives the native projects.
  • You prioritize developer velocity over native toolchain mastery (PHP-first teams adding mobile).
  • Your app targets internal use or limited distribution (QR install bypasses store constraints).
  • You're comfortable with MIT license and open-source dependencies (e.g., endroid/qr-code).

• Look elsewhere if:

  • You need App Store/Play Store submission (distribution signing, TestFlight, Play Console tracks remain manual and out of scope — signing is development only).
  • Your team has dedicated native developers who prefer Xcode/Android Studio.
  • You require advanced native modules beyond the provided bridges (custom camera pipelines, health, Bluetooth, complex permission flows). The bridge set grew — notifications, barcode, AdMob — but it is still a curated list, not an extension marketplace.
  • You want an vendor-neutral push stack — the notification path is designed around akyos/native-push, so plan for coupling or write your own sender against the token bridge.
  • Your asset pipeline is not Asset Mapper-based; v0.5.0 serves bridge Stimulus controllers through it, so a Webpack/Encore-only setup needs a bridging decision.
  • Your PHP version is <8.2 or Symfony version is outside 7.x/8.x.
  • You expect stable APIs — still pre-1.0, and the jump from v0.3.0 to v0.5.0 in a short window signals continued churn. Release notes are published in French, which adds onboarding friction for non-francophone teams.

How to Pitch It (Stakeholders)

For Executives:

"This package lets our Symfony backend team ship mobile interfaces dramatically faster by automating Android/iOS project setup end to end — scaffold, build, install, push notifications with deep-links, and now branding, in-app ads, and barcode scanning — all from PHP. Config changes like app name, icon, and top bar are re-applied automatically on every build instead of being re-done by hand or lost. Instead of waiting on native hires or wrestling with Xcode, the team can stand up a working native shell, put it on real devices, and re-engage users with notifications. It's a low-risk, zero-license-cost way to validate a mobile channel — and now to test monetization — before committing budget to a full native team."

Key Outcomes:

• Remove mobile dev bottlenecks for non-native teams; one CLI, one config file, synced on every build.
• Enable cross-platform testing (Android/iOS) from a single command line, including real iOS devices.
• Unlock retention experiments (push + deep-link) and revenue experiments (AdMob) without a separate mobile backend.
• Prove field-ops and inventory flows with the barcode bridge, rather than scoping a native module project.
• Lower tooling friction for MVP iterations, internal tools, and admin dashboards, with upgrades that don't require re-copying vendored assets.

For Engineering:

*"This is a Symfony-native wrapper for Hotwire Native builds. v0.5.0 shifts it from 'scaffolds a shell' to 'keeps the shell in sync with the app':

• Config re-injection: native:update:config rewrites native.yaml values (URL, name, icon, top bar) between markers without touching surrounding generated code, and adds missing bridges (--notification, --barcode-scanner, --admob). native:build runs it first, so what you build matches what you configured.
• Branding as code: iOS and Android icons generated from native.icon; the top bar is driven by Symfony path-configuration rules (top_bar) on both platforms.
• Asset handling: bridge Stimulus controllers are served via Asset Mapper from @akyos/ux-native-cli rather than copied into the project — upgrades stop being a manual merge.
• New bridges: barcode scanner and AdMob, plus NotificationTrait and ScanQRTrait for Live Components to wire notification and scan handling at the component level.
• Push notifications (from v0.3.0): --notification wires Firebase/APNs, exposes the device token via the notification-token bridge, and routes taps to a configured path — foregrounded or killed, both platforms. Send server-side with akyos/native-push.
• iOS device signing: ios_development_team plus -allowProvisioningUpdates gets builds onto physical devices without manual profile management.
• Navigation & resilience: Offline mode and path configuration for tabs, modals, and now the top bar.
• Build & install: Simulator and physical-device targets; --platform=android --no-install stays viable for CI artifacts.
• Debug ergonomics: WebView cache disabled in debug, cutting stale-asset confusion during bridge work.
• QR installs: native:qr-install serves builds over the air for stakeholder testing.

Trade-offs:

• Still not store-ready: development signing only; distribution certificates, TestFlight, and Play Console flows remain your responsibility.
• macOS required for iOS builds and device installs; Android works cross-platform.
• Asset Mapper dependency: bridge JS assumes Asset Mapper; confirm your asset pipeline before committing.
• Ecosystem coupling: the notification story assumes akyos/native-push on the server; the ad and scan stories assume the bundled bridges meet your needs (no plugin surface).
• Pre-1.0: small, active project — two minor versions since the last assessment, so expect API churn and pin versions. Release notes are in French.

Recommendation: Promote from 'prototype-only' to pilot-ready for internal tools and limited-distribution apps. Green-light a push-notification spike as previously scoped, and add a second timeboxed spike covering barcode scanning plus AdMob if monetization or field-ops is on the roadmap. Keep App Store submission out of the pilot's success criteria, and pin the package version in CI until a 1.0 lands."*