Imports

Imports allow you to use Go packages and GOX modules within the same file.

GOX preserves Go's import syntax and recognizes files .gox as application modules.

Import a Go package

The Go packages are imported through their usual route.

gox
import (
    "fmt"
    "net/http"
    "hello/billing"
    "github.com/gox-lang/gox"
)

After import, its members are used in the same way as in Go.

Import a GOX module

The GOX modules are imported by indicating the route of your file with the extension .gox.

gox
import "components/menu.gox"

Although the import contains a route, the code accesses members by the name declared by module.

The file components/menu.gox may declare:

gox
module menu

func Greeting(name string) string {
    return "Hola, " + name
}

Another module can import and use it as follows:

gox
module index

import (
    "github.com/gox-lang/gox"
    "components/menu.gox"
)

func GET(ctx *gox.Context) gox.Page {
    return <h1>{{menu.Greeting("George")}}</h1>
}

What can be imported

The import provides access to all public members of the module, including:

  • Funciones.
  • Variables.
  • Constantes.
  • Tipos.
  • Componentes.
  • Any other public statements.

Private members remain available only within the module that declares them.

Syntactic alias

A module can receive a local name within the sentence import.

gox
import navigation "components/menu.gox"

The alias replaces the module name only within the current file:

gox
message := navigation.Greeting("George")

This mechanism belongs to the syntax of the import and should not be confused with the routes that start with @, documented in Import aliases.

Import Components

The components use the same mechanism as any other public function.

gox
module menu

import "github.com/gox-lang/gox"

func Header(name string) gox.Component {
    return <header>
        <h1>{{name}}</h1>
    </header>
}

After importing the module, the component is invoked by name:

gox
module index

import (
    "github.com/gox-lang/gox"
    "components/menu.gox"
)

func GET(ctx *gox.Context) gox.Page {
    return <main>
        <&menu.Header name="George" />
    </main>
}

Project Go packages

A GOX project can also contain go-of-own packages. These packages use the structure and the usual rules of Go.

When you run:

bash
gox createproject hello

GOX creates the project with hello as the name of the module declared in go.mod:

go
module hello

From this module you can create Go packages in your own directories within the project root:

text
hello/
├── app/
├── billing/
│   ├── billing.go
│   └── invoice.go
├── client/
├── components/
├── pages/
├── public/
├── tests/
├── websocket/
├── go.mod
├── go.sum
└── gox.json

In this example, the files of billing/ belong to the package billing:

go
package billing

The package can be imported from a file .gox using the route formed by the module name and package directory:

gox
module index

import (
    "hello/billing"
    "github.com/gox-lang/gox"
)

func GET(ctx *gox.Context) gox.Page {
    invoice := billing.NewInvoice()

    return <p>{{invoice.Name}}</p>
}

Go's imports always refer to packages, not individual files. Therefore, it matters:

gox
"hello/billing"

It doesn't matter:

gox
"hello/billing/billing.go"

The project packages can also import other local packages using their normal routes:

go
import "hello/database"

It is not necessary to register these directories in gox.json. They are directly part of the module defined by go.mod and can be used both from files .go as from files .gox.

Combine Go and GOX

Go packages and GOX modules can be imported into the same block.

gox
module index

import (
    "strings"
    "components/menu.gox"
    "hello/billing"
    "github.com/gox-lang/gox"
)

func GET(ctx *gox.Context) gox.Page {
    name := strings.ToUpper("George")

    return <main>
        <&menu.Header name={{name}} />
    </main>
}

Hot reload

Changes made to files .gox do not restart the server. GOX only rewards the affected modules and dependencies, keeping the current instance active.

Changes made to files .go which belong to packages used by the application cause the complete reboot of the server.

GOX makes this reboot in an orderly manner:

  1. Executed OnStopServer.
  2. Close the current instance.
  3. Start a new instance.
  4. Executed OnStartServer.

As the new server uses a completely new runtime, the values stored in memory by gox.Storage are lost during restart.

Integration with Go

GOX uses the Go import syntax for both packages and application modules. .gox allows to distinguish the files to be solved by the GOX module system.

The syntactic aliases, the visibility of the identifiers and the access by the imported name retain the family behavior of Go. The special resolution of routes with @ is limited to GOX modules within pages/.

Best practices

  • Consistently group the Go packages and the GOX modules.
  • Includes extension .gox when importing a module.
  • It uses syntactic aliases only when they avoid conflict or improve clarity.
  • Avoid importing modules that are not used.
  • Use routes with @ to share or replace modules within the hierarchy of pages/.

To learn more about ModulesSee your documentation. To learn more about Components, check your documentation.

See also

Next step

Continue with Import aliases to know the hierarchical resolution and the shadowing of modules within pages/.

Import aliases