{"id":10644,"library":"codama","title":"Codama Solana Framework","description":"Codama is a Solana framework designed to facilitate the building of standardized programs through specifications and code generation. It aims to streamline the development of on-chain programs by providing a structured approach to defining program interfaces and interactions. The package `codama` (currently at version 1.6.0) serves as the main entry point, re-exporting core modules like `@codama/errors`, `@codama/nodes`, `@codama/validators`, and `@codama/visitors`, bundling them into a cohesive API. It offers utilities for managing Solana IDLs, allowing developers to create, manipulate, and validate program definitions from a `RootNode` or JSON representation. The project appears to have an active release cadence, with recent minor updates introducing new node types (e.g., `EventNode`) and functionality like a dynamic client for instruction building, indicating ongoing development and feature expansion within the Solana ecosystem.","status":"active","version":"1.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/codama-idl/codama","tags":["javascript","solana","framework","standard","specifications","code generation","typescript"],"install":[{"cmd":"npm install codama","lang":"bash","label":"npm"},{"cmd":"yarn add codama","lang":"bash","label":"yarn"},{"cmd":"pnpm add codama","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides error handling and dynamic client functionality for Codama programs.","package":"@codama/errors","optional":false},{"reason":"Defines the core Abstract Syntax Tree (AST) nodes for Solana program IDLs.","package":"@codama/nodes","optional":false},{"reason":"Provides TypeScript types for the AST nodes defined in @codama/nodes.","package":"@codama/node-types","optional":false},{"reason":"Offers validation logic for Codama IDL structures.","package":"@codama/validators","optional":false},{"reason":"Enables traversal and manipulation of Codama IDL ASTs using the visitor pattern.","package":"@codama/visitors","optional":false},{"reason":"Core utilities for implementing visitors in the Codama framework.","package":"@codama/visitor-core","optional":false}],"imports":[{"note":"This is primarily a TypeScript interface; runtime instances are created via helper functions.","symbol":"Codama","correct":"import type { Codama } from 'codama'"},{"note":"Prefer ESM imports. CommonJS `require` is not officially supported and may lead to issues.","wrong":"const { createFromRoot } = require('codama')","symbol":"createFromRoot","correct":"import { createFromRoot } from 'codama'"},{"note":"Functions are named exports, not default exports.","wrong":"import createFromJson from 'codama'","symbol":"createFromJson","correct":"import { createFromJson } from 'codama'"},{"note":"While ProgramNode is a type, `programNode` is the factory function to create an instance. The `codama` package re-exports `programNode` from `@codama/nodes`.","wrong":"import { ProgramNode } from 'codama'","symbol":"ProgramNode","correct":"import { programNode } from '@codama/nodes';\n// or direct from main package if re-exported\nimport { programNode } from 'codama'"}],"quickstart":{"code":"import { createFromJson, createFromRoot, programNode, type RootNode } from 'codama';\nimport { getDebugStringVisitor, consoleLogVisitor } from '@codama/visitors';\n\n// Example 1: Creating from a JSON string\nconst jsonIdlString = JSON.stringify({\n  version: '0.1.0',\n  name: 'my_program',\n  instructions: [\n    {\n      name: 'initialize',\n      accounts: [],\n      args: []\n    }\n  ],\n  accounts: [],\n  events: []\n});\n\nconst codamaFromJson = createFromJson(jsonIdlString);\nconsole.log('Codama from JSON:');\ncodamaFromJson.accept(consoleLogVisitor(getDebugStringVisitor({ indent: true })));\n\n// Example 2: Creating from a RootNode programmatically\nconst myProgramNode: RootNode = programNode({\n  name: 'myProgram',\n  version: '1.0.0',\n  docs: ['My example program.'],\n  instructions: [],\n  accounts: [],\n  errors: [],\n  types: [],\n  events: []\n});\n\nconst codamaFromRoot = createFromRoot(myProgramNode);\nconsole.log('\\nCodama from RootNode:');\ncodamaFromRoot.accept(consoleLogVisitor(getDebugStringVisitor({ indent: true })));\n\n// Example 3: Modifying a Codama instance (e.g., cloning)\nconst clonedCodama = codamaFromRoot.clone();\nconsole.log('\\nCloned Codama JSON:');\nconsole.log(clonedCodama.getJson());","lang":"typescript","description":"Demonstrates creating a Codama IDL instance from both JSON and a programmatic `RootNode`, then displaying and cloning it."},"warnings":[{"fix":"Ensure any custom IDL parsers or code generators are updated to optionally handle the presence of `EventNode` within `ProgramNode` structures. Refer to the `@codama/nodes` and `@codama/node-types` changelogs for full details.","message":"The Codama framework (specifically `@codama/nodes` and `@codama/node-types`) introduced a new `EventNode` to `ProgramNode` in version 1.6.0. While this is a minor addition and typically backward-compatible, consumers relying on a strict, fixed schema for IDL parsing or code generation might need to update their tooling to properly handle the new node type.","severity":"gotcha","affected_versions":">=1.6.0"},{"fix":"Review the `@codama/errors` documentation and examples if you plan to utilize or are affected by the new 'dynamic-client' for runtime instruction construction.","message":"The `@codama/errors` package, part of the core Codama monorepo, added a new 'dynamic-client' feature in version 1.6.0 for runtime Solana instruction building. While new functionality, users should be aware of potential integration impacts or new APIs to learn if they manage instruction building manually or through other libraries.","severity":"gotcha","affected_versions":">=1.6.0"},{"fix":"If a symbol is not found when importing directly from `codama`, try importing it from the specific sub-package it belongs to (e.g., `import { getDebugStringVisitor } from '@codama/visitors';`).","message":"Codama leverages a monorepo structure, and the main `codama` package primarily re-exports functionalities from its sub-packages (e.g., `@codama/nodes`, `@codama/visitors`). Direct imports from sub-packages might be necessary for specific, granular access, or if the main `codama` package doesn't re-export a specific symbol.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install codama` or `pnpm install codama` to add the package to your project's dependencies. Ensure your `tsconfig.json` includes `node_modules/@types` if using TypeScript.","cause":"The 'codama' package was not installed or is incorrectly referenced in the project.","error":"Error: Cannot find module 'codama' or its corresponding type declarations."},{"fix":"Ensure you are using ESM `import { createFromJson } from 'codama'` for TypeScript/modern JavaScript projects. If forced to use CommonJS, consider transpiling your code or using dynamic `import()`.","cause":"Attempting to import `createFromJson` using a CommonJS `require` statement in an ESM context, or using a default import syntax for a named export.","error":"TypeError: createFromJson is not a function"},{"fix":"Ensure the object passed to `programNode` or `createFromRoot` strictly adheres to the `ProgramNode` definition from `@codama/nodes` (or re-exported by `codama`), including all required fields and types. Check the latest `@codama/node-types` for schema updates, especially after major/minor version bumps.","cause":"Incorrectly providing an object literal that doesn't fully conform to the `ProgramNode` interface or using an outdated schema when trying to create a `RootNode`.","error":"Argument of type '{ name: string; version: string; instructions: never[]; accounts: never[]; errors: never[]; types: never[]; }' is not assignable to parameter of type 'ProgramNode'."}],"ecosystem":"npm"}