Wix Velo TypeScript False Module Warnings Explained and Resolved

by

Summary

A developer encountered TypeScript type-definition warnings (missing module errors) immediately upon generating a Wix Velo eCommerce Validation service plugin. While the IDE flags interfaces-ecommerce-v1-validations-provider as a missing module, the code often functions at runtime. The primary goal was to implement a stale checkout prevention mechanism to block payments on checkouts older than 29 minutes.

Root Cause

The issue is a disconnection between the Velo IDE’s static analysis engine and the platform’s runtime environment.

  • The interfaces-ecommerce-v1-validations-provider is a virtual module provided by the Wix runtime.
  • The IDE’s IntelliSense/TypeScript language server cannot resolve the path to these internal definition files because they are not hosted as physical files within the user’s project directory.
  • This results in a false positive “Cannot find module” warning, even though the underlying infrastructure injects these types during the build and deployment phase.

Why This Happens in Real Systems

This is a common occurrence in Low-Code/No-Code hybrid platforms and PaaS (Platform as a Service) environments.

  • Abstracted Dependencies: To simplify development, platforms hide complex SDKs and provide “magic” imports that only exist in the platform’s proprietary execution environment.
  • IDE Lag: The local linting tools and type checkers operate on a local file system, while the actual type definitions reside in a remote schema that the IDE fails to fetch or map correctly.
  • Template Drift: The auto-generated boilerplate is often updated in the runtime backend before the IDE’s type-definition manifests are synchronized.

Real-World Impact

  • Developer Friction: New engineers may waste hours attempting to “install” missing packages via npm, which is impossible in a closed ecosystem.
  • Confidence Erosion: Red squiggles in the editor lead developers to believe their code is broken, causing hesitation during deployment.
  • Maintenance Debt: If developers ignore all warnings due to these false positives, they may overlook actual syntax errors or genuine runtime bugs.

Example or Code (if necessary and relevant)

To implement the specific requirement of blocking checkouts older than 29 minutes, the implementation must focus on the checkout object properties and the BusinessError return type.

import * as ecomValidations from 'interfaces-ecommerce-v1-validations-provider';

export async function getValidationViolations(options, context) {
    const { checkout } = options;
    const createdDate = new Date(checkout._createdDate);
    const now = new Date();
    const diffInMinutes = (now - createdDate) / (1000 * 60);

    if (diffInMinutes > 29) {
        return {
            violations: [
                {
                    field: 'checkout',
                    message: 'This checkout has expired. Please start a new order.'
                }
            ]
        };
    }

    return { violations: [] };
}

How Senior Engineers Fix It

Senior engineers differentiate between Build-time Warnings and Runtime Failures.

  • Ignore the Lint: Once it is confirmed that the module is a platform-provided virtual interface, the warning is ignored.
  • Validation via Testing: Instead of relying on the IDE’s red squiggles, they use Live Site Testing or the Wix Testing Framework to verify the logic.
  • Defensive Coding: They use runtime type checks (e.g., checking if options.checkout exists) to ensure the code is resilient regardless of what the IDE claims about the types.
  • JSDoc Casting: In more strict environments, they use @ts-ignore or JSDoc @type casting to suppress the warning and restore IDE cleanliness.

Why Juniors Miss It

  • Over-reliance on Tooling: Junior developers often treat IDE warnings as absolute truth, assuming that if the editor says “Cannot find module,” the code cannot possibly run.
  • Lack of Environment Context: They may not realize the difference between a local node_module and a platform-injected dependency.
  • Tunnel Vision: They focus on fixing the “warning” (the symptom) rather than implementing the “logic” (the goal), leading them to try and fix the IDE configuration instead of writing the validation logic.

Leave a Comment