Skip to main content

​
Packages

Packages enable version control and dependency management at the project level by creating immutable snapshots of all components and their bound assets at a specific point in time. Each package uses semantic versioning and can be referenced by other projects.

​
Key Concepts

ConceptDescription
Immutable SnapshotsPackages cannot be modified after creation
Semantic VersioningUses MAJOR.MINOR.PATCH format (e.g., 1.0.0)
Auto-PublishingCreating a package publishes all draft/modified components
Asset BundlingAll component-bound assets are included
Dependency ResolutionProject dependencies are snapshotted

​
What Happens When You Create a Package

  1. Draft components (never published) → published status with version 1
  2. Modified components → published status with incremented version
  3. Published components (unchanged) → included at current version
  4. Collection structure is flattened (not preserved in packages)
  5. All bound assets are captured and included

​
Package Object

​
Fields

FieldTypeDescription
idstringUnique identifier (UUID)
projectIdstringSource project ID
versionstringSemantic version (e.g., 1.0.0)
componentsobject[]Array of component snapshots
components[].idstringComponent ID
components[].namestringComponent name
components[].typestringview or layout
components[].versionnumberComponent version at time of capture
assetsobject[]Array of bundled assets
assets[].idstringAsset ID
assets[].namestringAsset friendly name
assets[].urlstringCDN URL
assets[].componentIdstringOwning component ID
dependenciesobject[]Snapshotted project dependencies
compiledobjectRuntime-ready content
compiled.componentsobjectMap of component names to compiled code
compiled.assetsobjectMap of component names to asset arrays
metadataobjectPackage metadata
metadata.authorstringCreator
metadata.descriptionstringPackage description
metadata.tagsstring[]Categories
createdAtstringCreation timestamp
updatedAtstringLast update timestamp

​
Example Package

{
  "id": "pkg123",
  "projectId": "proj123",
  "version": "1.0.0",
  "components": [
    {
      "id": "comp123",
      "name": "ProductCard",
      "type": "view",
      "version": 5
    },
    {
      "id": "comp124",
      "name": "ArticleLayout",
      "type": "layout",
      "version": 2
    }
  ],
  "assets": [
    {
      "id": "asset123",
      "name": "logo-primary",
      "url": "https://cdn.metabind.ai/assets/logo-2x.png",
      "componentId": "comp123"
    }
  ],
  "compiled": {
    "components": {
      "ProductCard": "const body = (props) => { ... }",
      "ArticleLayout": "const body = (props, children) => { ... }"
    },
    "assets": {
      "ProductCard": [
        { "name": "logo-primary", "url": "https://cdn.metabind.ai/assets/logo-2x.png" }
      ]
    }
  },
  "dependencies": [
    {
      "projectId": "proj456",
      "version": "2.0.0"
    }
  ],
  "metadata": {
    "author": "[email protected]",
    "description": "Core UI components v1",
    "tags": ["ui", "core"]
  },
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}

​
Package Creation Process

​
Version Assignment

Previous StatusNew StatusVersion Change
draft (never published)publishednull → 1
modifiedpublishedn → n+1
published (unchanged)publishedNo change

​
Base URL

All package endpoints use this base path: 
/v1/organizations/:organizationId/projects/:projectId/packages