create-mini-app

An open-source project initialization CLI tool designed for building Safaricom Mini Programs using Tailwind CSS and standard web development tooling.

This tool allows you to bypass the graphical desktop IDE ("Mini Program Studio") during active coding, letting you write standard Tailwind CSS directly inside VS Code (or your preferred editor) and automatically compiles compatible outputs in real-time.

Quick Start

Initialize a new project directly from your terminal:

npx @meshark/create-mini-app my-new-store --template e-commerce

Options

• --template, -t: Choose a starter template (e-commerce or blank). If omitted, the CLI runs interactively.
• --typescript, --ts: Scaffolds the project using TypeScript with automatic typings for all Safaricom Mini Program APIs (my.*).
• --js, --javascript: Scaffolds the project using JavaScript.

Developer Workflow

To connect your editor workflow with the native Safaricom Mini Program Studio container simulator:

1. Start the Watcher: Navigate to your generated project folder and start the dev process:

   cd my-new-store
   npm run dev

   This starts an incremental compiler that watches files inside src/ and updates dist/ instantly.

2. Import into Mini Program Studio: Open Safaricom Mini Program Studio, choose Import Project, and select the compiled dist/ directory.

3. Develop in VS Code: Open my-new-store in VS Code and make edits inside src/. The watcher automatically compiles your changes, and the Mini Program Studio simulator will hot-reload the changes instantly.

Tailwind CSS Integration Engine

Native mobile containers reject escaped CSS selectors (like w-1/2 or hover:bg-green-500 containing backslashes, colons, or dots). create-mini-app solves this using a high-performance build compiler:

• Style Rewrite: A custom PostCSS plugin renames compiled Tailwind CSS rules (e.g. .w-1\/2 -> .w-1_2, .hover\:bg-green-500 -> .hover_bg-green-500, and .\!flex -> .i-flex).
• Markup Rewrite: The compiler scans .axml markup at build time. It searches for class, className, hover-class, and custom class attribute values, translating standard Tailwind classes to safe formats while preserving JavaScript expression structures within mustache template tags {{ ... }}.
• Responsive Sizing: Spacers, padding, margin, and fonts are pre-configured in tailwind.config.js using responsive rpx (responsive pixels) units, ensuring pixel-perfect scaling across physical mobile screens.

Project Structure

my-new-store/
├── package.json
├── tailwind.config.js         # Pre-configured with rpx scales and corporate colors
├── postcss.config.js          # Plugs in custom mini-program Tailwind plugin
├── scripts/
│   ├── build.js               # AXML class compiler and directory bundler
│   ├── watch.js               # Incremental hot-reload workspace watcher
│   └── postcss-miniprogram-tailwind.js
├── src/                       # Developer working directory (Edit code here!)
│   ├── app.js                 # Global data and lifecycle hook registrations
│   ├── app.json               # Tabbar navigation and window configurations
│   ├── app.acss               # Global tailwind directives entry point
│   ├── assets/
│   │   └── tabs/              # Tab navigation icon PNGs
│   └── pages/
│       ├── home/              # Grid product catalog with category filter tabs
│       ├── detail/            # Product image viewer and quantity adjuster
│       ├── cart/              # Item counts and checkout callbacks
│       └── orders/            # Completed transaction history lists
└── dist/                      # Compiled output folder (Import this into the Studio!)

Templates Included

E-Commerce (Default)

A production-ready storefront featuring:

• Items Catalog Grid: Interactive list with category filters.
• Product Details: Details view with quantity selectors.
• Shopping Cart: In-memory cart state, subtotal calculations, and product count adjustments.
• M-PESA Payment Checkout: Integrated with my.tradePay standard cashier payment window API.
• Order History: Local storage persistence caching completed M-PESA transactions and receipt codes.

Blank

A minimal boilerplate with the build engine and tailwind configurations prepared, ideal for custom designs.

Compilation Commands

• npm run dev: Runs the chokidar incremental file compiler. Watches src/ and updates modified files directly into dist/.
• npm run build: Runs a clean compile and generates optimized stylesheets and markup in dist/ ready to upload to the Safaricom Developer Console.