badgui/docs/source/development.rst

Development Mode
================

BadGUI provides two development workflows: **Instant Development** with ``bg.dev()`` and **Static Project Generation** with ``bg.build()``.

Instant Development with bg.dev()
----------------------------------

The ``bg.dev()`` method provides the fastest development experience by automatically:

1. Creating a temporary project build
2. Installing npm dependencies 
3. Starting the development server
4. Opening your app in the browser
5. Cleaning up temporary files on exit

Basic Usage
~~~~~~~~~~~

.. code-block:: python

    import badgui as bg

    with bg.page("/", "HomePage", "My App"):
        bg.label("Hello World!").classes("text-h3 text-primary")
        bg.button("Click Me").classes("q-btn-primary")

    # 🚀 One command does it all!
    bg.dev()

Run your script::

    python my_app.py

The server starts automatically at ``http://localhost:9000``.

Configuration Options
~~~~~~~~~~~~~~~~~~~~~

Customize the development server:

.. code-block:: python

    bg.dev(
        port=3000,              # Custom port (default: 9000)
        host="localhost",       # Bind to specific host (default: localhost)
        auto_reload=False,      # Auto-rebuild on file changes (default: False)
        project_name="my-app"   # Temporary project name (default: badgui-dev)
    )

Advanced Example
~~~~~~~~~~~~~~~~

.. code-block:: python

    import badgui as bg

    def create_app():
        with bg.page("/", "HomePage", "Development Demo"):
            bg.label("🚀 Live Development Mode").classes("text-h2 text-center q-mb-lg")
            
            with bg.row().classes("justify-center q-gutter-md") as row:
                bg.button("Primary").classes("q-btn-primary")
                bg.button("Secondary").classes("q-btn-secondary")
                bg.button("Accent").classes("q-btn-accent")
            
            with bg.column().classes("q-mt-lg max-width-sm mx-auto") as form:
                bg.input(placeholder="Name").classes("q-mb-md").props("filled")
                bg.input(placeholder="Email").classes("q-mb-md").props("filled type=email")
                bg.button("Submit").classes("q-btn-primary full-width")

    if __name__ == "__main__":
        create_app()
        
        # Development mode with custom settings
        bg.dev(
            port=3000,
            host="0.0.0.0",  # Accept connections from any IP
            project_name="live-demo"
        )

Benefits of bg.dev()
~~~~~~~~~~~~~~~~~~~~

- **Zero Setup**: No manual ``npm install`` or server commands
- **Fast Iteration**: Make changes and refresh browser
- **Temporary Files**: No clutter in your project directory
- **Automatic Cleanup**: Temp files removed on exit
- **Cross-Platform**: Works on Windows, macOS, and Linux

Multi-Page Development
~~~~~~~~~~~~~~~~~~~~~~

``bg.dev()`` works seamlessly with multi-page applications:

.. code-block:: python

    import badgui as bg

    # Home page
    with bg.page("/", "HomePage", "Home"):
        bg.label("Welcome Home").classes("text-h3")
        bg.link("Go to About", "/about").classes("q-btn q-btn-primary")

    # About page  
    with bg.page("/about", "AboutPage", "About"):
        bg.label("About Us").classes("text-h3")
        bg.link("Back Home", "/").classes("q-btn q-btn-secondary")

    # Contact page
    with bg.page("/contact", "ContactPage", "Contact"):
        bg.label("Contact Us").classes("text-h3")
        bg.input(placeholder="Message").props("filled type=textarea")
        bg.button("Send").classes("q-btn-primary")

    # Start development server
    bg.dev(port=8080)

Static Project Generation
-------------------------

For production deployment or when you need full control over the build process, use ``bg.build()``.

Basic Build
~~~~~~~~~~~

.. code-block:: python

    import badgui as bg

    with bg.page("/", "HomePage", "Production App"):
        bg.label("Production Ready").classes("text-h3")

    # Generate static project
    bg.build(
        output_dir="./dist",           # Output directory
        project_name="my-prod-app",    # Project name
    )

Manual Development
~~~~~~~~~~~~~~~~~~

After building, you can develop manually::

    cd dist
    npm install
    npm run dev        # Development server
    npm run build      # Production build

Deployment
~~~~~~~~~~

Build for production deployment::

    cd dist
    npm install
    npm run build
    
    # Deploy the dist/ folder contents to your web server

When to Use Each Mode
---------------------

**Use bg.dev() when:**

- 🚀 Rapid prototyping and development
- ⚡ Quick testing of UI changes
- 🔧 Learning BadGUI features
- 💻 Local development and experimentation

**Use bg.build() when:**

- 🌐 Preparing for production deployment
- 📦 Need to customize the build process
- 🔧 Integrating with CI/CD pipelines
- 📝 Sharing projects with frontend developers

Best Practices
--------------

Development Workflow
~~~~~~~~~~~~~~~~~~~

1. **Start with bg.dev()** for rapid development
2. **Use version control** to track your Python code
3. **Test different devices** using ``host="0.0.0.0"``
4. **Switch to bg.build()** when ready for deployment

Project Organization
~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    # main.py
    import badgui as bg
    from pages import home, about, contact

    def main():
        home.create_page()
        about.create_page()  
        contact.create_page()
        
        if __name__ == "__main__":
            bg.dev(port=3000)

    # pages/home.py
    import badgui as bg

    def create_page():
        with bg.page("/", "HomePage", "Home"):
            bg.label("Home Page Content")

Troubleshooting
---------------

**Port Already in Use**

.. code-block:: python

    # Try a different port
    bg.dev(port=3001)

**npm Not Found**

Install Node.js from https://nodejs.org/

**Permission Errors**

.. code-block:: bash

    # Linux/macOS - fix npm permissions
    sudo chown -R $(whoami) ~/.npm

**Slow Dependencies Install**

.. code-block:: python

    # The first run installs dependencies (can take 1-2 minutes)
    # Subsequent runs are much faster

**Browser Not Opening**

Manually navigate to the URL shown in the terminal output.

Examples
--------

Complete examples using ``bg.dev()`` are available in the :doc:`examples` section.