Package Imports

This page explains how Targo projects consume Go packages and when declaration refresh is required.

Core Rule

When imports, dependencies, or binder-related config change, refresh declarations before trusting type information.

In most projects that means:

npm run targo init

Import Model

• Import Go packages directly from Targo source.
• Treat imported packages as Go packages first, not JavaScript modules.
• Prefer current generated declarations over stale assumptions from earlier runs.

Common Import Shapes

Use the import shape that matches how the package is exposed in generated declarations.

Namespace-style package import

Use this when the package is consumed like a Go package namespace:

import * as json from "encoding/json";

const err = json.Unmarshal(data, target);

Named import for common functions

Use this when the generated declarations expose package functions directly:

import { New } from "errors";
import { Errorf } from "fmt";
import { Join } from "strings";

Do not assume Node or JavaScript module conventions. Check the declaration shape first when unsure.

Common Error Construction Patterns

import { New } from "errors";

return [zero<Result>(), New("missing config")];

import { Errorf } from "fmt";

return [zero<Result>(), Errorf("invalid config %s: %v", name, err)];

import { Join } from "strings";

const message = Join(messages, "; ");
return [zero<Result>(), Errorf("validation failed: %s", message)];

Prefer these Go-shaped package APIs over JavaScript-style global helpers.

Binding and Declarations

• Standard library and package declarations are generated by the Targo toolchain.
• tsconfig.targo.json is the generated bridge file that pulls declaration sources into the TS project.
• types/** is used for local Go directory bindings.
• Project-local .targo/ is only expected in vendored or backward-compatibility flows.
• If imported package types look wrong, regenerate instead of editing generated files.

When To Refresh

Refresh when you change:

• go.mod
• imported Go packages
• binder configuration
• targo.json
• workspace dependency layout that affects declarations

Practical Rules

• Do not hand-edit generated declarations.
• Treat declaration generation issues as tooling problems to regenerate or debug, not as source files to patch manually.
• If a type is missing after adding a package, verify that the package is actually part of the current Go module and binding flow.
• When exploring package usage, check whether the project uses namespace imports (import * as json) or named imports (import { Errorf }) before inventing a new import style.
• For error creation and wrapping, prefer Go package functions such as errors.New and fmt.Errorf over JavaScript exception habits.