Saltar al contenido principal

Instalación en Angular

Aprende cómo instalar y configurar el Sistema de Diseño de Tiendana para proyectos Angular.

Requisitos Previos​

  • Node.js 20.x o superior (requisito de @tiendana/utils)
  • Angular 19.x o superior
  • Gestor de paquetes npm o yarn

Instalación​

Autenticación Requerida

Los paquetes @tiendana están alojados en AWS CodeArtifact privado, no en el registro público de npm. Autentica npm con Tiendana CLI (tdn auth npm) antes de instalar.

📖 Guía completa: Configuración de CodeArtifact

1. Autenticarse con CodeArtifact​

tdn auth npm

O en la app de la barra de menú: Tiendana CLI → Registries → npm → Refresh. El proyecto necesita además el .npmrc que dirige el scope @tiendana a CodeArtifact; ver Configurar el Proyecto.

2. Instalar Paquetes​

Una vez autenticado, instala los paquetes:

npm install @tiendana/ngx-core @tiendana/utils @tiendana/web-foundation

O usando yarn:

yarn add @tiendana/ngx-core @tiendana/utils @tiendana/web-foundation
Versiones de esta documentación

Esta documentación se escribió contra @tiendana/ngx-core ^0.9.0, @tiendana/utils ^0.5.0 y @tiendana/web-foundation ^0.5.5. En versiones 0.x el rango ^ no cruza de minor (^0.8.0 nunca resuelve 0.9.0), así que actualiza los tres en el mismo cambio.

3. Dependencias Peer​

@tiendana/ngx-core 0.9.0 declara estas dependencias peer:

PaqueteRangoObligatoria
@angular/core, @angular/common>=19.xSí
@tiendana/api-types>=1.x.xSí
@tiendana/utils>=0.4.0Sí
@ngx-translate/core>=16.0.4Sí
@angular/router>=19.xOpcional
@tiendana/web-foundation>=0.5.4Opcional
@amplitude/analytics-browser>=2.xOpcional

Si tu proyecto aún no los tiene, instálalos explícitamente. Con una versión menor de @tiendana/utils o @tiendana/web-foundation, npm falla con ERESOLVE.

npm install @tiendana/api-types @ngx-translate/core

Si importas cualquier cosa de @tiendana/ngx-core/tracking, instala también @amplitude/analytics-browser y @angular/router: el punto de entrada los importa de forma estática aunque no uses AmplitudeProvider.

Configuración​

1. Importar Estilos​

Los estilos de Web Foundation se importan en el styles.scss global. La entrada styles compila la hoja completa (reset, tipografía, componentes y utilidades):

@use '@tiendana/web-foundation/styles';

También puedes cargar el CSS ya compilado desde angular.json, importando el subpath exportado /css y no la ruta de archivo dentro de node_modules:

{
  "projects": {
    "tu-proyecto": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "@tiendana/web-foundation/css",
              "src/styles.scss"
            ]
          }
        }
      }
    }
  }
}
Tokens sin CSS

@use '@tiendana/web-foundation' as tdn; (sin /styles) solo expone variables, funciones y mixins SCSS: no emite ningún CSS. Úsalo para leer tokens (tdn.$spacing-md) o mixins (tdn.respond-to(md)), además de importar la hoja completa. Consulta CSS/HTML para ver las entradas disponibles.

2. Registrar Providers​

Registra en app.config.ts los providers que necesitan los componentes que uses:

import { ApplicationConfig, LOCALE_ID } from '@angular/core';
import { registerLocaleData } from '@angular/common';
import localeEs from '@angular/common/locales/es';
import { provideRouter } from '@angular/router';
import { TDN_DATE_FORMATTER, DateFormatter } from '@tiendana/ngx-core/forms';

import { routes } from './app.routes';

registerLocaleData(localeEs);

const dateFormatter: DateFormatter = {
    format: (date: Date) =>
        new Intl.DateTimeFormat('es-ES', { day: '2-digit', month: '2-digit', year: 'numeric' }).format(date),
    formatRange: (from: Date, to: Date) => {
        const formatter = new Intl.DateTimeFormat('es-ES', { day: '2-digit', month: '2-digit', year: 'numeric' });
        return `${formatter.format(from)} - ${formatter.format(to)}`;
    }
};

export const appConfig: ApplicationConfig = {
    providers: [
        provideRouter(routes),
        { provide: LOCALE_ID, useValue: 'es-ES' },
        { provide: TDN_DATE_FORMATTER, useValue: dateFormatter }
    ]
};
TDN_DATE_FORMATTER es obligatorio con tdn-input-date

TdnInputDateComponent inyecta TDN_DATE_FORMATTER sin valor por defecto. Si usas tdn-input-date y no registras el provider, Angular lanza NullInjectorError al crear el componente. Ver tdn-input-date.

Otros providers según lo que uses:

Si usasNecesitas
tdn-order-statusUn TranslateService configurado con las claves PEDIDO_* (@ngx-translate/core)
TrackingprovideTracking({ ... }) desde @tiendana/ngx-core/tracking, con @angular/router y @amplitude/analytics-browser instalados

3. Importar Componentes​

El paquete tiene un punto de entrada por área. Todos los componentes son standalone, así que se importan directamente en cada componente:

Entry pointContenido
@tiendana/ngx-coreRaíz del paquete; solo exporta NGX_CORE_VERSION
@tiendana/ngx-core/uiDrawer, backdrop, tabs, status, timeline, stepper, display templates y más
@tiendana/ngx-core/formstdn-form-element, inputs, tdn-select, errores y FormRevealService
@tiendana/ngx-core/pipesPipes de transformación de datos
@tiendana/ngx-core/validatorsValidadores y utilidades de lectura de archivos
@tiendana/ngx-core/trackingTrackingService, tdnTrack y proveedores de analítica
@tiendana/ngx-core/logomark<tdn-logomark>, el logomark animado de Tiendana
import { Component } from '@angular/core';
import { DrawerComponent } from '@tiendana/ngx-core/ui';

@Component({
    selector: 'app-example',
    standalone: true,
    imports: [DrawerComponent],
    template: `
        <drawer #drawer>
            <p>Contenido del drawer</p>
        </drawer>
        <button class="bttn bttn--primary" (click)="drawer.open()">
            Abrir Drawer
        </button>
    `
})
export class ExampleComponent {}

4. Importar Utilidades​

Importa utilidades de @tiendana/utils según sea necesario:

import { deepMerge, Patterns, copyTextToClipboard } from '@tiendana/utils';

const merged = deepMerge(obj1, obj2);
const valid = Patterns.EMAIL.test('usuario@ejemplo.com');

await copyTextToClipboard('Texto a copiar');

El paquete declara sideEffects: false, por lo que el bundler descarta lo que no uses. El logomark vive en su propio punto de entrada (@tiendana/utils/logomark) y no forma parte del barrel raíz. Para usarlo desde Angular consulta tdn-logomark.

Solo entradas documentadas

@tiendana/utils define un exports map: solo se pueden importar @tiendana/utils y @tiendana/utils/logomark desde TypeScript, y @tiendana/utils/logomark/colourways desde SCSS (@use). Los imports profundos (@tiendana/utils/dist/...) ya no resuelven.

Próximos Pasos​