Nuxt GitLab

GitLab integration module for Nuxt. Provides typed composables and secure server-side APIs to interact with GitLab repositories.

• ✨  Release Notes

Features

• 🔐  Secure server-side GitLab token handling
• 🌿  Fetch Git references (branches & tags)
• 🧩  Typed composables (useGitlab)
• 🛡  Zod-based request validation (shared client & server)
• 🏗  Works with GitLab SaaS and self-hosted GitLab
• 🧪  Playground for local development

Quick Setup

Install the module in your Nuxt application:

npx nuxt module add nuxt-gitlab

Or using your package manager:

npm install nuxt-gitlab

Add the module to your Nuxt config:

export default defineNuxtConfig({
  modules: ['nuxt-gitlab'],
})

Configuration Environment Variables (Recommended)

⚠️ Never commit real GitLab tokens to your repository.

NUXT_GITLAB_API_URL=https://gitlab.com/api/v4
NUXT_GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxx

Nuxt Config

export default defineNuxtConfig({
  modules: ['nuxt-gitlab'],

  gitlab: {
    baseUrl: process.env.NUXT_GITLAB_API_URL,
    token: process.env.NUXT_GITLAB_TOKEN,
  },
})

Usage

Fetch Git references (branches or tags)

<script setup lang="ts">
const { getRefs } = useGitlab()

const branches = await getRefs({
  projectId: 5940,
  type: 'branches',
})
</script>

Options

interface GitlabRefsInput {
  projectId: string | number
  type?: 'branches' | 'tags'
}

Fetch repository tree

<script setup lang="ts">
const { getTree } = useGitlab()

const { data: tree } = await useAsyncData(
  'gitlab-tree',
  () =>
    getTree({
      projectId: 5940,
      branch: 'develop',
    }),
)
</script>

Options

interface GitlabTreeInput {
  projectId: string | number
  branch: string
}

Fetch multiple file contens

<script setup lang="ts">
const { getFiles } = useGitlab()

const { data: files } = await useAsyncData(
  'gitlab-files',
  () =>
    getFiles({
      projectId: 5940,
      branch: 'develop',
      paths: [
        'content/1.moon-index.md',
        'content/content/articles',
      ],
    }),
)
</script>

Options

interface GitlabFilePullInput {
  projectId: string | number
  branch: string
  paths: string[]
}

License

MIT

Nuxt Compatibility

Nuxt 4, Nuxt 3

Roadmap

📂 Repository tree API

📄 File content API

🔄 Pagination support

🧪 Extended test coverage