Migration Guide v2.0.1

Guide for upgrading from WebApp v1.x to v2.0.1

Migration Guide: Upgrading to WebApp v2.0.1

This guide helps you migrate from WebApp v1.x to the new v2.0.1 release, which introduces significant new features and some breaking changes.

What's New in v2.0.1

  • MySQL Database Support: Full MySQL integration with query builder
  • OpenAPI v3.0 Documentation: Automatic API documentation generation
  • Enhanced WebSocket Support: Improved real-time communication
  • Advanced Routing: Better authentication and permissions
  • Form Validators: Built-in validation system
  • WebApp CLI Enhancements: Improved development tools

Breaking Changes

1. Dart Version Requirement

v1.x: Dart 2.12+ v2.0.1: Dart 3.0+

# pubspec.yaml
environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  webapp: ^2.0.1

2. Import Changes

Some imports have been reorganized:

// OLD (v1.x)
import 'package:webapp/wa_server.dart';
import 'package:webapp/wa_route.dart';

// NEW (v2.0.1) - Same imports, but new features available
import 'package:webapp/wa_server.dart';
import 'package:webapp/wa_route.dart';
import 'package:webapp/wa_mysql.dart';     // NEW: MySQL support
import 'package:webapp/wa_openapi.dart';  // NEW: OpenAPI support

3. Configuration Changes

Server configuration has new optional parameters:

// OLD (v1.x)
WaConfigs configs = WaConfigs(
  widgetsPath: pathTo('./widgets'),
  languagePath: pathTo('./languages'),
  port: 8085,
  dbConfig: WaDBConfig(enable: false),
  publicDir: pathTo('./public'),
);

// NEW (v2.0.1) - Same config, with new optional features
WaConfigs configs = WaConfigs(
  widgetsPath: pathTo('./widgets'),
  languagePath: pathTo('./languages'),
  port: 8085,
  dbConfig: WaDBConfig(enable: false),
  publicDir: pathTo('./public'),
  // NEW: Optional MySQL configuration
  mysqlConfig: MySQLConfig(
    host: 'localhost',
    username: 'user',
    password: 'pass',
    database: 'mydb',
  ),
);

Step-by-Step Migration

Step 1: Update Dependencies

Update your pubspec.yaml:

dependencies:
  webapp: ^2.0.1
  # Update other dependencies as needed

environment:
  sdk: '>=3.0.0 <4.0.0'

Run dependency update:

dart pub upgrade

Step 2: Update Dart Version

If you haven't already, update to Dart 3.0+:

# Check current version
dart --version

# Update Dart (if using Flutter)
flutter upgrade

# Or update Dart SDK directly
# Follow instructions at https://dart.dev/get-dart

Step 3: Review Your Code

Most v1.x code will continue to work in v2.0.1. However, review these areas:

Server Initialization

Your existing server setup should work without changes:

// This continues to work in v2.0.1
WaServer server = WaServer(configs: configs);

final socketManager = SocketManager(
  server,
  event: SocketEvent(
    onConnect: (socket) {
      // Your existing WebSocket code
    },
  ),
  routes: getSocketRoute(),
);

void main() async {
  server.addRouting(getWebRoute);
  server.start().then((value) {
    Console.p('Server started: http://localhost:${value.port}');
  });
}

Routing

Your existing routes will continue to work:

// Existing routes work unchanged
Future<List<WebRoute>> getWebRoute(WebRequest rq) async {
  return [
    WebRoute(
      path: '/',
      rq: rq,
      index: homeController.index,
    ),
    // Your existing routes...
  ];
}

Step 4: Add New Features (Optional)

Take advantage of new v2.0.1 features:

Enable OpenAPI Documentation

void main() async {
  var server = WaServer(configs: configs);
  
  // NEW: Enable OpenAPI documentation
  server.enableOpenAPI(
    title: 'My WebApp API',
    version: '1.0.0',
    description: 'My application API',
  );
  
  server.addRouting(getWebRoute);
  await server.start();
}

Now access your API docs at: http://localhost:8085/docs

Add MySQL Support

// NEW: MySQL integration
import 'package:webapp/wa_mysql.dart';

class UserController extends WaController {
  Future<void> getUsers() async {
    var query = Q()
      .selects([QSelectAll()])
      .from(QField('users'))
      .where(WhereOne(QField('status'), QO.EQ, QVar('active')))
      .limit(10);
    
    var result = await mysqlConnection.execute(query.toSQL());
    return rq.renderJson({'data': result});
  }
}

Enhance API Documentation

@OpenAPIController(tag: 'Users')
class UserController extends WaController {
  
  @OpenAPIOperation(
    summary: 'Get all users',
    responses: {
      200: OpenAPIResponse(description: 'Users retrieved successfully'),
    },
  )
  Future<void> getUsers() async {
    // Your existing code
  }
}

Testing Your Migration

1. Basic Functionality Test

Ensure your existing functionality works:

# Start your application
dart run
# or
webapp run

# Test your existing endpoints
curl http://localhost:8085/

2. New Features Test

Test new features if you've enabled them:

# Test OpenAPI documentation
curl http://localhost:8085/openapi.json

# View Swagger UI
open http://localhost:8085/docs

3. WebApp CLI Test

Test the enhanced CLI:

# Update WebApp CLI
dart pub global activate webapp

# Test CLI commands
webapp --version
webapp --help

Common Migration Issues

Issue 1: Dart Version Conflicts

Problem: Dart version compatibility issues

Solution:

# Update Dart to 3.0+
flutter upgrade
# or follow Dart installation guide

# Clean and rebuild
dart pub cache clean
dart pub get

Issue 2: Dependency Conflicts

Problem: Dependency version conflicts

Solution:

# Update all dependencies
dart pub upgrade

# If conflicts persist, check dependency_overrides in pubspec.yaml

Issue 3: Import Errors

Problem: New import paths not found

Solution:

// Ensure you're importing from the correct package
import 'package:webapp/wa_mysql.dart';    // For MySQL features
import 'package:webapp/wa_openapi.dart';  // For OpenAPI features

Performance Considerations

Database Connections

v2.0.1 introduces connection pooling for better performance:

// Configure connection pool for production
var mysqlConfig = MySQLConfig(
  host: 'localhost',
  username: 'user',
  password: 'pass',
  database: 'mydb',
  poolSize: 10,  // NEW: Connection pooling
  timeout: Duration(seconds: 30),
);

Memory Management

v2.0.1 has improved memory management, but consider these best practices:

// Use connection pooling for database operations
// Close resources properly in controllers
// Use appropriate caching strategies

Rollback Plan

If you encounter issues, you can rollback to v1.x:

# pubspec.yaml
dependencies:
  webapp: ^1.1.2  # Last stable v1.x version

environment:
  sdk: '>=2.12.0 <4.0.0'

dart pub downgrade

Getting Help

Resources

Reporting Migration Issues

When reporting migration issues, include:

  1. WebApp version (before and after)
  2. Dart/Flutter version
  3. Operating system
  4. Error messages
  5. Minimal code example

Conclusion

WebApp v2.0.1 provides significant new capabilities while maintaining backward compatibility for most use cases. The migration should be straightforward for most applications, and the new features provide substantial value for modern web application development.

Take your time to test thoroughly, and don't hesitate to reach out for help if you encounter any issues during the migration process.

Edit this page
WebApp 2.0.1 Features
Comprehensive overview of WebApp package features and capabilities
Installing
Installing WebApp Package dart