# What Is the Core Library in the CommonGrants Project?

> Discover the CommonGrants core library at @common-grants/core. Learn about its foundational namespace, diagnostics, and utility functions powering the entire ecosystem.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: deep-dive
- Published: 2026-03-03

---

**The core library in the CommonGrants project is the `@common-grants/core` TypeSpec library located in `lib/core`, which defines the foundational namespace, diagnostics, and utility functions used across the entire ecosystem.**

The CommonGrants protocol, developed in the `hhs/simpler-grants-protocol` repository, relies on a centralized core library to maintain type consistency across its various implementations. This **core library in the CommonGrants project** serves as the single source of truth for the `CommonGrants` namespace and provides the building blocks for downstream packages like the TypeScript SDK.

## Understanding the @common-grants/core TypeSpec Library

### Library Definition and Registration

The core library is instantiated using `createTypeSpecLibrary` from the `@typespec/compiler` package. In [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts), the library is defined with the name `@common-grants/core` and prepares an empty diagnostics object for future extensions:

```typescript
export const $lib = createTypeSpecLibrary({
  name: "@common-grants/core",
  diagnostics: {
    // We'll add diagnostics later if needed
  },
} as const);

```

### Exported Utilities for Diagnostics

Beyond the library instance, the core exports helper functions for diagnostic reporting. The same file extracts `reportDiagnostic` and `createDiagnostic` from the library instance:

```typescript
export const { reportDiagnostic, createDiagnostic } = $lib;

```

## Integration Points and Usage Across the Ecosystem

### Entry Point Exports

The main entry point at [`lib/core/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/index.ts) re-exports the library instance, making it available for external consumption:

```typescript
export { $lib } from "./lib.js";

```

### SDK Implementation References

Downstream consumers like the TypeScript SDK reference namespaces defined by the core library. The SDK's Zod schemas map to `CommonGrants.Types`, `CommonGrants.Filters`, and `CommonGrants.Fields`, all of which originate from the core library definitions. For example, in [`lib/ts-sdk/src/schemas/zod/types.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/schemas/zod/types.ts):

```typescript
/**
 * Types for the CommonGrants.Types namespace in the @common-grants/core library.
 */
export const GrantType = z.enum(["grant", "subgrant"]);

```

## Summary

- The **core library in the CommonGrants project** is the `@common-grants/core` TypeSpec package located in `lib/core`.
- It is defined in [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts) using `createTypeSpecLibrary` and exports `$lib`, `reportDiagnostic`, and `createDiagnostic`.
- The library establishes the `CommonGrants` namespace used by the TypeScript SDK and other downstream implementations.
- It serves as the foundational layer for type definitions, diagnostics, and utility functions across the entire protocol ecosystem.

## Frequently Asked Questions

### What file defines the core library in the CommonGrants project?

The core library is defined in [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts), where `createTypeSpecLibrary` instantiates the `@common-grants/core` library with its configuration and diagnostic definitions.

### How does the TypeScript SDK use the core library?

The SDK references namespaces defined by the core library—such as `CommonGrants.Types`, `CommonGrants.Filters`, and `CommonGrants.Fields`—to construct Zod schemas that validate data structures against the protocol specifications.

### What utilities does the core library export for error handling?

The core library exports `reportDiagnostic` and `createDiagnostic` functions from [`lib/core/src/lib.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/lib.ts), which provide standardized mechanisms for creating and reporting compiler diagnostics throughout the TypeSpec ecosystem.

### Where is the core library entry point for external imports?

External modules import the core library through [`lib/core/src/index.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/core/src/index.ts), which re-exports the `$lib` instance, making the library's symbols available to downstream packages like the TypeScript SDK.