Guía de migración

Esta guía cubre la migración de MONEI Components v2 a v3. Si estás empezando desde cero, consulta la descripción general de los componentes o ve directamente a la página de tu framework.

Novedades en v3

• Paquetes dedicados por framework — @monei-js/react-components, @monei-js/vue-components, @monei-js/angular-components, @monei-js/svelte-components
• API submit() — llama a submit() directamente en la instancia del componente en lugar de createToken()
• Props tipadas — soporte completo de TypeScript para todas las props y eventos de los componentes
• Soporte para Svelte 5 — nuevo paquete @monei-js/svelte-components
• Modal de pago — llama a confirmPayment() sin token para abrir un modal de checkout completo

Cambio de URL del CDN

- <script src="https://js.monei.com/v2/monei.js"></script>
+ <script src="https://js.monei.com/v3/monei.js"></script>

Cambio de paquete npm

- npm install @monei-js/components@1.x
+ npm install @monei-js/components@2.x

Cambios en las importaciones por framework

La API .driver() se sustituye por paquetes dedicados por framework. Cada paquete exporta componentes nativos — sin necesidad de wrappers ni puentes.

Vanilla JS

Sin cambios en las importaciones — Vanilla JS usa @monei-js/components tanto en v2 como en v3.

import {CardInput} from '@monei-js/components';

const cardInput = CardInput({paymentId: '...'});
cardInput.render('#card-input');

React

- import {CardInput, createToken} from '@monei-js/components';
- import React, {useRef} from 'react';
- const ReactCardInput = CardInput.driver('react', {React});
+ import {CardInput} from '@monei-js/react-components';

Ya no necesita el polyfill de ReactDOM ni findDOMNode.

Vue

- import {CardInput, createToken} from '@monei-js/components';
- const MoneiCardInput = CardInput.driver('vue3');
+ import {CardInput} from '@monei-js/vue-components';

Sin más __bridgeInstance — usa template refs directamente.

Angular

- import {CardInput} from '@monei-js/components';
- import {Component, NgModule, ElementRef, NgZone, Inject} from '@angular/core';
- const CardInputModule = CardInput.driver('angular', {
-   Component, NgModule, ElementRef, NgZone, Inject
- });
+ import {MoneiCardInput} from '@monei-js/angular-components';

Todos los componentes son standalone — no se requiere NgModule. Usa bindings @Input() tipados en lugar de una bolsa de props opaca [props]:

- <!-- Old: untyped props bag -->
- <bridge-component [props]="{paymentId: id, onChange: handler}"></bridge-component>
+ <!-- New: typed individual inputs -->
+ <monei-card-input
+   [paymentId]="id"
+   [accountId]="accountId"
+   [onChange]="handler"
+   [onFocus]="focusHandler"
+   [style]="inputStyle">
+ </monei-card-input>

Svelte

Paquete nuevo — no existía un driver de Svelte anteriormente.

import {CardInput} from '@monei-js/svelte-components';

Requiere Svelte 5 (API de runes).

Migración de createToken() → submit()

La función independiente createToken(instance) se sustituye por instance.submit(). El tipo de retorno es el mismo: {token?: string, error?: string}.

Vanilla JS

Antes:

import {CardInput, createToken} from '@monei-js/components';

const cardInput = CardInput({paymentId: '...'});
cardInput.render('#card-input');
const {token} = await createToken(cardInput);

Después:

import {CardInput} from '@monei-js/components';

const cardInput = CardInput({paymentId: '...'});
cardInput.render('#card-input');
const {token} = await cardInput.submit({cardholderName: 'John'});

React

Antes:

import {createToken} from '@monei-js/components';

const ref = useRef(null);
const {token} = await createToken(ref.current, {cardholderName: 'John'});

Después:

import {CardInput, type CardInputHandle} from '@monei-js/react-components';

const ref = useRef<CardInputHandle>(null);
const {token} = await ref.current!.submit({cardholderName: 'John'});

Vue

Antes:

import {createToken} from '@monei-js/components';

const {token} = await createToken(cardInputRef.value.__bridgeInstance);

Después:

import {CardInput} from '@monei-js/vue-components';

const cardInput = ref<InstanceType<typeof CardInput>>();
const {token} = await cardInput.value!.submit({cardholderName: 'John'});

Angular

Antes:

// No typed submit() — had to access internal bridge instance

Después:

import {MoneiCardInput} from '@monei-js/angular-components';

@ViewChild('cardInput') cardInput!: MoneiCardInput;
const {token} = await this.cardInput.submit({cardholderName: 'John'});

Svelte

Paquete nuevo — usa bind:this para referencias a componentes:

<script lang="ts">
  import {CardInput} from '@monei-js/svelte-components';

  let cardInput: CardInput;

  async function handleSubmit() {
    const {token} = await cardInput.submit({cardholderName: 'John'});
  }
</script>

<CardInput bind:this="{cardInput}" {paymentId} />

Qué NO ha cambiado

nota

monei.api.createToken() (usado en Apple Pay y Google Pay para el intercambio de tokens de monedero) es una API diferente y no está obsoleta. Solo la función de nivel de componente createToken(instance) está obsoleta.

APIs obsoletas

Las siguientes APIs aún funcionan en v3 pero muestran advertencias de deprecación en la consola:

Obsoleta	Sustitución
.driver('react', {React})	import from '@monei-js/react-components'
.driver('vue3')	import from '@monei-js/vue-components'
.driver('angular', {...})	import from '@monei-js/angular-components'
createToken(instance)	instance.submit()

Estas APIs obsoletas se eliminarán en una futura versión principal.