Skip to content

TUTORIAL_ID.md

Latest commit

 

History

History
765 lines (585 loc) · 15.2 KB

TUTORIAL_ID.md

File metadata and controls

765 lines (585 loc) · 15.2 KB
Raw

Ercode CLI - Tutorial Lengkap (Bahasa Indonesia)

Daftar Isi

  1. Pengenalan
  2. Instalasi
  3. Konsep Dasar
  4. Tutorial Step-by-Step
  5. Contoh Kasus Nyata
  6. Tips dan Trik
  7. FAQ

Pengenalan

Apa itu Ercode CLI?

Ercode CLI adalah tool command-line yang membantu developer Flutter untuk membuat modul CRUD dengan cepat. Alih-alih mengetik ratusan baris kode secara manual, Anda cukup membuat file konfigurasi JSON sederhana, dan Ercode CLI akan men-generate semua kode yang diperlukan.

Apa yang Bisa Di-generate?

Untuk setiap modul, Ercode CLI akan membuat:

  • ✅ Model: Class untuk data dengan serialisasi JSON
  • ✅ Repository: Class untuk komunikasi dengan API
  • ✅ List View: Halaman untuk menampilkan daftar data
  • ✅ Add/Edit View: Halaman form untuk tambah/edit data
  • ✅ Detail View: Halaman untuk melihat detail data
  • ✅ Controllers: Logic untuk mengatur state setiap halaman

Keuntungan Menggunakan Ercode CLI

  • ⚡ Cepat: Generate modul lengkap dalam hitungan detik
  • 🎯 Konsisten: Struktur kode yang seragam di seluruh project
  • 🐛 Minim Bug: Template sudah teruji
  • 📚 Best Practice: Mengikuti arsitektur yang baik
  • 🔄 Reusable: Widget dan helper yang bisa dipakai ulang

Instalasi

Langkah 1: Install Ercode CLI

Buka terminal dan jalankan:

# Menggunakan Dart
dart pub global activate ercode_cli

# ATAU menggunakan Flutter
flutter pub global activate ercode_cli

Langkah 2: Verifikasi Instalasi

ercode

Jika berhasil, akan muncul:

 ercode

   init                          to init ercode generator
   generate <folder/generator.json>      to generate code

Langkah 3: Setup PATH (Opsional)

Jika command ercode tidak ditemukan, tambahkan ke PATH:

macOS/Linux:

export PATH="$PATH":"$HOME/.pub-cache/bin"

Tambahkan baris di atas ke ~/.bashrc atau ~/.zshrc

Windows: Tambahkan %USERPROFILE%\AppData\Local\Pub\Cache\bin ke Environment Variables

Konsep Dasar

Struktur Project

Setelah menggunakan Ercode CLI, struktur project Anda akan seperti ini:

my_app/
├── lib/
│   ├── helpers/           # Fungsi-fungsi pembantu
│   ├── models/            # Model global
│   ├── widgets/           # Widget reusable
│   └── modules/           # Modul-modul yang digenerate
│       ├── book/
│       │   ├── data/
│       │   ├── controllers/
│       │   └── views/
│       ├── user/
│       └── product/
└── generator/             # Folder untuk simpan config JSON
    ├── book.json
    ├── user.json
    └── product.json

Alur Kerja Ercode CLI

JSON Config → Ercode CLI → Generated Code → Flutter App
  1. Anda buat file JSON yang mendefinisikan struktur modul
  2. Ercode CLI membaca JSON tersebut
  3. Ercode CLI men-generate kode berdasarkan template
  4. Anda tinggal gunakan kode yang sudah di-generate

Tutorial Step-by-Step

Tutorial 1: Hello Ercode - Modul Sederhana

Mari kita buat aplikasi sederhana untuk mengelola daftar buku.

Step 1: Buat Project Flutter Baru

flutter create my_library_app
cd my_library_app

Step 2: Inisialisasi Ercode

ercode init

Proses ini akan:

  • Install packages yang diperlukan
  • Membuat folder helpers/, widgets/, models/
  • Generate helper files
  • Modifikasi main.dart

Proses ini memakan waktu beberapa menit. Tunggu sampai selesai!

Step 3: Konfigurasi API

Edit file lib/helpers/constants.dart:

const baseUrl = 'https://api.example.com/api';
const apiToken = ''; // Kosongkan jika tidak pakai token

Catatan: Untuk tutorial ini, Anda bisa pakai API dummy atau mock API

Step 4: Buat Folder Generator

mkdir generator

Step 5: Buat File Konfigurasi JSON

Buat file generator/book.json:

{
  "name": "book",
  "fields": [
    {
      "name": "id",
      "type": "int",
      "primary": true,
      "hidden": true
    },
    {
      "name": "title",
      "type": "String",
      "list": true
    },
    {
      "name": "author",
      "type": "String",
      "list": true
    },
    {
      "name": "year",
      "type": "int",
      "list": true
    },
    {
      "name": "description",
      "type": "String"
    }
  ]
}

Penjelasan:

  • "name": "book" → Nama modul
  • "primary": true → Ini adalah ID/primary key
  • "hidden": true → Tidak ditampilkan di form (karena auto-generated dari server)
  • "list": true → Field ini ditampilkan di halaman list

Step 6: Generate Code

ercode generate generator/book.json

Output:

File model lib/modules/book/data/book.dart created
File repo lib/modules/book/data/book_repository.dart created
File controller : lib/modules/book/controllers/book_controller.dart created
File view: lib/modules/book/views/book_view.dart created
...

Step 7: Jalankan Flutter Pub Get

flutter pub get

Step 8: Gunakan View yang Sudah Di-generate

Edit lib/main.dart, ubah home:

import 'package:my_library_app/modules/book/views/book_view.dart';

// ...

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Get.navigatorKey,
      builder: EasyLoading.init(),
      home: BookView(), // Tambahkan ini
    );
  }
}

Step 9: Run App

flutter run

Selamat! Anda sudah punya aplikasi dengan fitur:

  • ✅ List buku
  • ✅ Tambah buku baru
  • ✅ Edit buku
  • ✅ Hapus buku
  • ✅ Lihat detail buku

Tutorial 2: E-Commerce Product dengan Upload Gambar

Step 1: Buat JSON Config

Buat generator/product.json:

{
  "name": "product",
  "api": "products",
  "fields": [
    {
      "name": "id",
      "type": "int",
      "primary": true,
      "hidden": true
    },
    {
      "name": "image",
      "type": "String",
      "input": "image",
      "list": true
    },
    {
      "name": "name",
      "type": "String",
      "list": true
    },
    {
      "name": "price",
      "type": "int",
      "list": true
    },
    {
      "name": "stock",
      "type": "int",
      "list": true
    },
    {
      "name": "description",
      "type": "String"
    },
    {
      "name": "category",
      "type": "String"
    }
  ]
}

Perbedaan dari sebelumnya:

  • "input": "image" → Field ini adalah upload gambar
  • "api": "products" → Custom endpoint API

Step 2: Generate

ercode generate generator/product.json

Step 3: Hasil

File yang di-generate akan otomatis handle:

  • Image picker
  • Image upload ke server (multipart form)
  • Image preview di list
  • Image crop (jika diperlukan)

Tutorial 3: Generate Sebagian (Model Only)

Kadang Anda hanya butuh model tanpa view.

Step 1: Buat JSON Config

Buat generator/category.json:

{
  "name": "category",
  "only": ["model", "repository"],
  "fields": [
    {
      "name": "id",
      "type": "int",
      "primary": true
    },
    {
      "name": "name",
      "type": "String"
    },
    {
      "name": "icon",
      "type": "String"
    }
  ]
}

Key point:

  • "only": ["model", "repository"] → Hanya generate model dan repository

Step 2: Generate

ercode generate generator/category.json

Hanya akan membuat:

  • lib/modules/category/data/category.dart
  • lib/modules/category/data/category_repository.dart

Tidak membuat views dan controllers!

Contoh Kasus Nyata

Kasus 1: Aplikasi Toko Online

Modul yang dibutuhkan:

  1. Product (dengan gambar)
  2. Category
  3. Order
  4. Customer

File JSON:

generator/product.json

{
  "name": "product",
  "fields": [
    {"name": "id", "type": "int", "primary": true, "hidden": true},
    {"name": "image", "input": "image", "list": true},
    {"name": "name", "list": true},
    {"name": "price", "type": "int", "list": true},
    {"name": "stock", "type": "int", "list": true},
    {"name": "description"},
    {"name": "category_id", "type": "int", "hidden": true}
  ]
}

generator/category.json

{
  "name": "category",
  "only": ["model", "repository"],
  "fields": [
    {"name": "id", "type": "int", "primary": true},
    {"name": "name"}
  ]
}

generator/order.json

{
  "name": "order",
  "fields": [
    {"name": "id", "type": "int", "primary": true, "hidden": true},
    {"name": "customer_name", "list": true},
    {"name": "total_price", "type": "int", "list": true},
    {"name": "status", "list": true},
    {"name": "order_date", "list": true},
    {"name": "shipping_address"}
  ]
}

Generate semua:

ercode generate generator/product.json
ercode generate generator/category.json
ercode generate generator/order.json

Kasus 2: Aplikasi Blog

Modul yang dibutuhkan:

  1. Post (artikel blog)
  2. Author
  3. Comment

generator/post.json

{
  "name": "post",
  "fields": [
    {"name": "id", "type": "int", "primary": true, "hidden": true},
    {"name": "featured_image", "input": "image", "list": true},
    {"name": "title", "list": true},
    {"name": "slug", "hidden": true},
    {"name": "content"},
    {"name": "excerpt", "list": true},
    {"name": "author_name", "list": true},
    {"name": "published_at", "list": true},
    {"name": "is_published", "type": "bool"}
  ]
}

Kasus 3: Aplikasi Inventory

generator/item.json

{
  "name": "item",
  "fields": [
    {"name": "id", "type": "int", "primary": true, "hidden": true},
    {"name": "photo", "input": "image", "list": true},
    {"name": "code", "list": true},
    {"name": "name", "list": true},
    {"name": "quantity", "type": "int", "list": true},
    {"name": "unit"},
    {"name": "location"},
    {"name": "last_restock"}
  ]
}

Tips dan Trik

Tip 1: Organisasi File JSON

Buat struktur folder untuk config JSON:

generator/
├── modules/
│   ├── product.json
│   ├── category.json
│   └── user.json
└── backups/
    └── old_configs/

Tip 2: Naming Convention

✅ Good:

{"name": "product"}
{"name": "user_profile"}
{"name": "order_item"}

❌ Bad:

{"name": "Product"}
{"name": "user profile"}
{"name": "orderItem"}

Tip 3: Primary Key Pattern

Selalu buat field ID seperti ini:

{
  "name": "id",
  "type": "int",
  "primary": true,
  "hidden": true
}

Tip 4: Field untuk List View

Pilih 3-5 field penting untuk ditampilkan di list:

// GOOD - Ringkas dan informatif
{"name": "title", "list": true},
{"name": "author", "list": true},
{"name": "date", "list": true}

// BAD - Terlalu banyak
{"name": "field1", "list": true},
{"name": "field2", "list": true},
...
{"name": "field10", "list": true}

Tip 5: Hidden Fields

Gunakan hidden: true untuk field yang:

  • Auto-generated server (id, created_at, etc)
  • Internal use only
  • Tidak perlu input user
{
  "name": "created_by",
  "type": "int",
  "hidden": true
}

Tip 6: Custom API Endpoint

Jika endpoint API berbeda dengan nama modul:

{
  "name": "user_profile",
  "api": "users",
  "fields": [...]
}

Tip 7: Force Overwrite

Untuk replace file yang sudah ada:

ercode generate generator/book.json force

Hati-hati! Ini akan menimpa semua modifikasi manual!

Tip 8: Backup Before Force

Sebelum pakai force, backup dulu:

# Backup folder modules
cp -r lib/modules lib/modules_backup

# Atau backup specific module
cp -r lib/modules/book lib/modules/book_backup

Tip 9: Git Ignore Generated Code (Opsional)

Jika Anda ingin re-generate setiap kali, tambahkan ke .gitignore:

lib/modules/*/

Tapi commit file JSON config:

!generator/

Tip 10: Format Code Setelah Generate

ercode generate generator/book.json
dart format lib/

FAQ

Q: Apakah bisa customize kode yang sudah di-generate?

A: Bisa! Tapi jika Anda run generate lagi dengan flag force, modifikasi Anda akan hilang. Solusinya:

  • Extend class yang di-generate
  • Atau jangan pakai flag force

Q: Bagaimana jika struktur API saya berbeda?

A: Anda bisa modifikasi template di folder lib/templates/. Atau modifikasi kode hasil generate sesuai kebutuhan.

Q: Apakah bisa generate untuk API GraphQL?

A: Default-nya untuk REST API. Untuk GraphQL, Anda perlu modifikasi template repository.

Q: Error "File already exists"

A: File sudah ada. Pilihan:

  1. Hapus manual
  2. Pakai flag force: ercode generate config.json force

Q: Error import setelah generate

A: Run:

flutter pub get
dart fix --apply

Q: Gimana cara handle relasi antar model?

A: Ercode CLI fokus ke basic CRUD. Untuk relasi, Anda perlu custom manual di kode yang di-generate.

Q: Bisa pakai state management lain (Bloc, Riverpod)?

A: Default menggunakan StatefulWidget. Untuk state management lain, modifikasi template controller.

Q: Apakah ada limit jumlah field?

A: Tidak ada limit, tapi untuk UX yang baik, maksimal 10-15 field per form.

Q: Bisa generate untuk web/desktop?

A: Kode yang di-generate compatible dengan Flutter web/desktop, tapi beberapa widget (image_picker) mungkin perlu adjustment.

Q: Error saat ercode init

A:

  1. Pastikan internet stabil
  2. Cek Flutter SDK sudah terinstall
  3. Run flutter doctor

Q: Bagaimana cara update Ercode CLI?

A:

dart pub global activate ercode_cli

Atau force update:

dart pub global activate ercode_cli --force

Q: Dimana saya bisa laporkan bug?

A: Buka issue di GitHub: https://github.com/xrb21/ercode_cli/issues

Troubleshooting

Problem: Command 'ercode' not found

Solution:

  1. Cek instalasi: 
    dart pub global list
  2. Tambahkan ke PATH (lihat bagian Instalasi)
  3. Restart terminal

Problem: Init lambat/stuck

Solution:

  1. Cek koneksi internet
  2. Coba manual install dependency: 
    flutter pub add dio
flutter pub add validators
# dst...

Problem: Generate error "Module not found"

Solution: Cek:

  1. Path JSON benar
  2. Format JSON valid (gunakan JSON validator online)
  3. Field name ada dan tidak kosong

Problem: API always return error

Solution:

  1. Cek baseUrl di constants.dart
  2. Test API dengan Postman/curl
  3. Cek network permission di AndroidManifest.xml
  4. Enable logging di api.dart

Problem: Image upload tidak jalan

Solution:

  1. Cek permission di AndroidManifest.xml: 
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.CAMERA"/>
  2. Request permission di runtime (Android 6+)

Problem: List view kosong

Solution:

  1. Cek API response format (lihat dokumentasi)
  2. Cek console untuk error message
  3. Pastikan ada field dengan "list": true

Penutup

Selamat! Anda sudah menguasai Ercode CLI.

Untuk dokumentasi lengkap, lihat:

Happy Coding! 🚀

Dibuat dengan ❤️ untuk Flutter developers Indonesia