# Imports and name resolution (https://docs-dmpho5eos-ton-core-docs.vercel.app/llms/tolk/syntax/imports/content.md)



In practice, contract code is split across multiple files. Projects with multiple contracts share a single codebase, including messages, storage layouts, and related logic. Symbols defined in one file can be used in another by importing that file. After an import, all its public symbols are available to the importing file.

## Importing files [#importing-files]

Error codes are commonly placed in a separate file, for example `errors.tolk`:

```tolk
const ERR_ZERO_BALANCE = 123
// ...
```

To use these constants in `parse.tolk`, the file must be imported explicitly:

```tolk
import "errors"

fun validate(balance: coins) {
    assert (balance > 0) throw ERR_ZERO_BALANCE;
}
```

<Callout type="tip">
  When selecting items from auto-completion, [IDE](/llms/contract-dev/ide/overview/content.md) inserts imports automatically. This works in both JetBrains-based and VSCode-based IDEs.
</Callout>

## Name uniqueness [#name-uniqueness]

All top-level symbols must have unique names.

* There is no `export const ...` or `export fun ...` declarations needed.
* All constants, functions, and other top-level declarations are visible by default.
* No module-private symbols exist.

As a result, all top-level symbols across imported files must have unique names. Declaring `fun log()` in multiple files causes a duplicate declaration error when both files are imported.

Techniques to avoid name collisions:

1. Use long, descriptive names for top-level symbols, especially in multi-contract projects.
   * Good: `ReturnExcessesBack`, `WalletStorage`.
   * Bad: `Excesses`, `Storage`.
2. Group integer constants to enums.
3. [Prefer methods to global-scope functions](/llms/languages/tolk/idioms-conventions/content.md).

## Repeated symbols across contracts [#repeated-symbols-across-contracts]

When developing multiple contracts, each contract has its own file and compilation target. Place a [`contract` declaration](/llms/languages/tolk/features/contract-abi/content.md) in every entrypoint file:

```tolk
// file: ContractA.tolk
import "storage"
import "errors"

contract ContractA {
    storage: StorageA
    incomingMessages: MsgsA
}

fun onInternalMessage(in: InMessage) {
    // ...
}

get fun name() {
    return "a"
}
```

```tolk
// file: ContractB.tolk
import "storage"
import "errors"
import "ContractA"   // brings types from ContractA, but NOT its entrypoints

contract ContractB {
    storage: StorageB
    incomingMessages: MsgsB
}

fun onInternalMessage(in: InMessage) {
    // ...
}

get fun name() {
    return "b"
}
```

`onInternalMessage`, `onExternalMessage`, and `get fun` belong to a specific contract. When a file declares `contract`, importing it exposes its types and functions but **not** these entrypoints — so `ContractB` can reuse `ContractA`'s storage and messages without any naming conflicts on `onInternalMessage` or get methods.

In addition, when `contract` is present, all entrypoints must live in the same file as the `contract` declaration; importing a file that declares a `get fun` is not allowed.

In a multi-contract project, each contract file typically contains only:

* its `contract` declaration,
* its entrypoints,
* and contract-specific logic.

The remaining codebase — messages, errors, utils, shared storage structs — is split into supplementary files that every contract may `import`.

## Import path mappings [#import-path-mappings]

Apart from relative paths, the `import` statement can accept `@`-aliases:

```tolk
import "@common/jettons"
import "@third_party/math-lib"
```

This mechanism resembles path mappings in TypeScript, i.e., `paths` in `tsconfig.json`. Unlike `paths`, Tolk does not use file masks: each alias is specified independently.

Specify mappings at compiler invocation:

<CodeGroup>
  <CodeBlockTabs defaultValue="Command line">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Command line">
        Command line
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="tolk-js">
        tolk-js
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Blueprint">
        Blueprint
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Command line">
      ```bash  icon="terminal"
      tolk --path-mapping @common=/some/dir --path-mapping @third_party=/another/dir ...
      ```
    </CodeBlockTab>

    <CodeBlockTab value="tolk-js">
      ```javascript  icon="file-js"
      runTolkCompiler({
          // ...
          pathMappings: {
              "@common": "/some/dir",
              "@third_party": "/another/dir",
          }
      })
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Blueprint">
      ```typescript  icon="file-js"
      // ContractName.compile.ts
      export const compile: CompilerConfig = {
          // ...
          pathMappings: {
              "@common": "/some/dir",
              "@third_party": "/another/dir",
          }
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

Mapped aliases can point to absolute or relative directories:

```text
"@node_modules": "../../../node_modules"
```