Packages, Modules & Imports

Packages: Go’s module system

TypeScript uses ES modules (import/export) with npm for packages. Go has a similar concept: packages (a directory of .go files sharing a package declaration) and modules (a collection of packages defined by go.mod, like package.json).

Packages and the package declaration

Every Go file starts with package <name>. Files in the same directory share a package. Executable programs use package main.

// TypeScript: file is automatically a module
export function add(a: number, b: number): number {
    return a + b;
}
export const PI = 3.14159;

// Go: explicit package declaration
package mathutil

func Add(a, b int) int {
    return a + b
}

const PI = 3.14159

Exported vs unexported identifiers

Go’s export system is elegantly simple: capitalise the first letter → exported (public). lowercase → unexported (private to the package). No export keyword needed.

// TypeScript: explicit export keyword
export function PublicFunc() { ... }
function privateFunc() { ... }   // not exported

export class PublicClass { ... }
class InternalClass { ... }

// Go: capitalisation IS the export keyword
func PublicFunc() { ... }   // exported — capital P
func privateFunc() { ... }  // unexported — lowercase p

type PublicStruct struct { ... }
type internalStruct struct { ... }

go.mod — the package.json equivalent

// package.json (npm)
{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0"
  }
}

// Add dependency:
// npm install express

// go.mod
module github.com/user/my-app

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
)

// Add dependency:
// go get github.com/gin-gonic/gin

Importing packages

// TypeScript
import { readFileSync } from 'fs';
import express from 'express';
import { add } from './mathutil';

// Go
import (
    "os"                           // stdlib
    "github.com/gin-gonic/gin"     // third-party
    "github.com/user/app/mathutil" // local package
)

Try it

Open in Playground

package main

import (
  "fmt"
  "strings"
  "unicode"
)

func isExported(name string) bool {
  if name == "" {
    return false
  }
  return unicode.IsUpper(rune(name[0]))
}

func main() {
  names := []string{"Println", "printf", "HTTP", "myHelper", "PublicAPI"}
  for _, n := range names {
    status := "unexported"
    if isExported(n) {
      status = "EXPORTED"
    }
    fmt.Printf("%-12s -> %s\n", n, status)
  }

  s := "go for typescript developers"
  fmt.Println(strings.ToTitle(s))
}

🟦 Capitalisation as the export mechanism

This is one of Go’s most distinctive design choices. There is no public, private, protected, or export keyword. The first letter of any identifier (function, type, variable, constant, struct field) determines visibility:

Exported — capital first letter — visible outside the package
unexported — lowercase first letter — package-private

type User struct {
    Name  string  // exported field
    email string  // unexported field — callers can't access this
}

You can instantly tell from any identifier whether it’s part of a package’s public API just by reading the code.

🟦 init() — package initialisation

Each Go package can have an init() function that runs automatically when the package is first imported, before main(). You cannot call init() directly.

package db

var pool *sql.DB

func init() {
    var err error
    pool, err = sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatal(err)
    }
}

The Node.js equivalent is top-level code that runs when a module is first require()d, but Go’s init() is explicit and well-defined.