Un proyecto Dart no es solo un conjunto de archivos; es una entidad organizada que sigue un contrato estricto para que el SDK pueda entenderla. El corazón de este contrato es el archivo pubspec.yaml. Este archivo es el manifiesto que le dice al SDK de Dart qué es tu proyecto, qué versión del motor necesita para ejecutarse y qué piezas externas (dependencias) requiere para funcionar. Si intentas usar un nombre de paquete con mayúsculas o espacios, o si defines mal las versiones, el comando pub get fallará y no podrás ni siquiera importar una librería básica. Entender esto es vital porque, si el manifiesto es incorrecto, el compilador perderá el rastro de todas las dependencias y tu proyecto simplemente no arrancará.
Cuando inicias un proyecto, el SDK te entrega una estructura de carpetas con roles muy específicos. La carpeta lib/ es el cerebro; allí reside la lógica real que puede ser reutilizada. Si estás creando una herramienta para la terminal (una aplicación), usarás bin/ para definir el punto de entrada ejecutable. Si lo que creas es una librería para que otros la usen, bin/ es innecesario. Para asegurar la calidad, usas test/ para tus pruebas y analysis_options.yaml para establecer las reglas de estilo que el editor te recordará constantemente.
A continuación, veamos cómo se ve un archivo pubspec.yaml bien configurado para una herramienta de línea de comandos:
# El nombre debe ser en snake_case (minúsculas y guiones bajos)
name: procesador_datos_pro
description: Una herramienta CLI para transformar archivos JSON de forma masiva.
# Versión siguiendo el estándar semántico (major.minor.patch)
version: 1.2.0
# Define la restricción del SDK de Dart para asegurar compatibilidad
environment:
sdk: '^3.4.0'
# Dependencias necesarias para que el programa funcione al ejecutarse
dependencies:
args: ^2.4.0
path: ^1.8.0
# Dependencias que solo usas mientras programas o testeas
dev_dependencies:
test: ^1.24.0
lints: ^3.0.0
# Metadatos útiles para publicar el paquete
homepage: https://github.com/usuario/procesador_datos_pro
repository: { type: git, url: https://github.com/usuario/procesador_datos_pro }
issue_tracker: https://github.com/usuario/procesador_datos_pro/issues
En el ejemplo anterior, el campo name utiliza snake_case, lo cual es obligatorio para que los comandos de Dart funcionen sin problemas. El campo environment con sdk: '^3.4.0' establece un contrato: el proyecto solo funcionará en versiones de Dart que sean compatibles con la 3.4.0, evitando errores de compatibilidad con funciones nuevas o cambios en el motor.
Fíjate en la distinción entre dependencies y dev_dependencies. Si tu programa necesita la librería args para leer los comandos que el usuario escribe en la terminal, esta debe ir en dependencies, porque sin ella el programa fallará al ejecutarse. Sin embargo, la librería test solo la necesitas mientras estás desarrollando y verificando que todo esté bien; cuando entregues tu aplicación final, test no es necesaria para el usuario final, por eso va en dev_dependencies.
Un detalle crucial es el archivo pubspec.lock. Aunque no lo ves en el ejemplo de código, se genera automáticamente cuando ejecutas pub get. Este archivo es una “fotografía” de las versiones exactas de todas tus dependencias. En una aplicación, siempre debes subir este archivo a tu control de versiones (como Git) para que todos los desarrolladores y el servidor de producción usen exactamente las mismas versiones. En cambio, si estás creando una librería (un package), es mejor no subirlo para permitir que los usuarios de tu librería tengan flexibilidad con las versiones de sus propias dependencias.
Cuando ejecutas pub get, el SDK genera un archivo oculto en .dart_tool/package_config.json. No lo toques manualmente; es el mapa interno que usa el compilador para localizar físicamente dónde están instaladas las librerías en tu disco duro.
El error frecuente
El error más común al editar un pubspec.yaml es el error de indentación. YAML es extremadamente sensible a los espacios.
# ESTO ESTÁ MAL Y CAUSARÁ UN ERROR DE PARSEO dependencies: args: ^2.4.0 json_serializable: ^6.0.0 # Si esto tuviera un espacio de más o de menos, fallará extra_dep: ^1.0.0 # Error: la indentación debe ser consistente
Si una dependencia no tiene exactamente el mismo nivel de sangría que las anteriores, el comando dart pub get lanzará un error de formato. Un pequeño espacio extra puede romper la estructura de todo el proyecto.
N° 6