Bootstrap npm Kurulumu: Paket Yöneticileri, Webpack, Parcel ve Derleme Araçları

CDN mi, paket yöneticisi mi?

CDN bağlantısı tek bir HTML sayfasında ya da derleme adımı olmayan küçük projelerde en hızlı yoldur. Paket yöneticisi ise projenizde zaten bir derleme süreci varsa, Bootstrap'in Sass kaynaklarını özelleştirmek istiyorsanız ya da yalnızca kullandığınız JavaScript eklentilerini pakete almak istiyorsanız anlam kazanır. "Download" sayfası önemli bir noktayı vurgular: hangi paket yöneticisini kullanırsanız kullanın, resmî derlenmiş sürümlerle aynı sonucu almak için bir Sass derleyicisine ve Autoprefixer'a ihtiyacınız olur. Derlenmiş CSS'i doğrudan içe aktarırsanız bu ikisine gerek kalmaz.

npm ile kurulum

npm install bootstrap

Kurulumdan sonra const bootstrap = require('bootstrap') ya da import bootstrap from 'bootstrap' tüm eklentileri bir bootstrap nesnesine yükler; paketin ana modülü bütün eklentileri dışa aktarır. Yalnızca birkaç eklentiye ihtiyacınız varsa paketin kök dizinindeki js/dist/*.js dosyalarını tek tek yükleyebilirsiniz.

Paketin package.json dosyası, araçların doğru dosyayı bulması için bazı ek anahtarlar taşır. Belgeler iki tanesini özellikle anar: sass ana Sass kaynak dosyasını, style ise varsayılan ayarlarla önceden derlenmiş ve küçültülmemiş CSS dosyasını gösterir. v5.0.2 paketindeki ilgili alanlar şöyledir:

{
  "style": "dist/css/bootstrap.css",
  "sass": "scss/bootstrap.scss",
  "main": "dist/js/bootstrap.js",
  "module": "dist/js/bootstrap.esm.js",
  "license": "MIT",
  "peerDependencies": {
    "@popperjs/core": "^2.9.2"
  }
}

main alanı UMD biçimindeki bootstrap.js dosyasını, module alanı ise ESM biçimindeki bootstrap.esm.js dosyasını gösterir; license alanı da kodun MIT lisanslı olduğunu belirtir. Popper dependencies içinde değil peerDependencies içinde tanımlıdır. Bu, npm'in Popper'ı sizin yerinize otomatik eklemeyeceği anlamına gelir; Webpack ve Parcel sayfaları onu ayrıca kurmanızı ister:

npm install @popperjs/core

Diğer paket yöneticileri

Download sayfası npm dışında dört seçenek daha listeler. Hepsi Bootstrap'in kaynak dosyalarını projenize getirir:

# yarn
yarn add bootstrap

# RubyGems (Bundler kullanmıyorsanız)
gem install bootstrap -v 5.0.2

# Composer
composer require twbs/bootstrap:5.0.2

# NuGet: CSS sürümü ya da Sass sürümü
Install-Package bootstrap
Install-Package bootstrap.sass

Ruby projelerinde belgelerin önerdiği yol Bundler'dır: Gemfile dosyanıza gem 'bootstrap', '~> 5.0.2' satırını eklersiniz. Gem'in kendi README dosyası ek ayrıntılar içerir. .NET projelerinde NuGet ile CSS ya da Sass sürümünü seçebilirsiniz; Composer ise PHP projelerinde Sass ve JavaScript dosyalarını yönetmenizi sağlar.

Webpack ile kullanım

JavaScript'i içe aktarmak

Uygulamanızın giriş dosyasına, genellikle index.js ya da app.js, ihtiyacınız olan eklentileri adlarıyla içe aktarırsınız. Yalnızca bir iki eklenti gerekiyorsa onları js/dist altından tek tek de alabilirsiniz:

// İhtiyacınız olan eklentileri adlarıyla seçin
import { Tooltip, Toast, Popover } from 'bootstrap';

// Ya da tek bir eklentiyi doğrudan dosyasından alın
import Alert from 'bootstrap/js/dist/alert';

"Optimize" sayfası, bootstrap/js/dist altındaki dosyaların varsayılan dışa aktarım (default export) kullandığını belirtir. Bu yüzden tek bir eklentiyi aldığınızda adını kendiniz verir ve örneğini o adla oluşturursunuz:

import Modal from 'bootstrap/js/dist/modal'

const modal = new Modal(document.getElementById('myModal'))

Aynı sayfa, açılır menü, tooltip veya popover içe aktarıyorsanız Popper bağımlılığını package.json dosyanızda listelemenizi hatırlatır. Eklentilerin ortak yöntemleri ve olayları JavaScript API yazısında.

Sass kaynaklarını derlemek

Bootstrap'i tam olarak özelleştirmek için kaynak dosyaları paketleme sürecinize katarsınız. Belgelerin önerdiği yapıda kendi _custom.scss dosyanızda değişkenleri ezersiniz, ana Sass dosyanızda da önce bu dosyayı, sonra Bootstrap'i içe aktarırsınız:

@import "custom";
@import "~bootstrap/scss/bootstrap";

Bu yapının derlenmesi için belgeler şu yükleyicileri kurmanızı ister: sass-loader, Autoprefixer ile birlikte postcss-loader ve sonuçları sayfaya bağlayan css-loader ile style-loader. Belgelerdeki en küçük Webpack kuralı şöyledir (yorumlar Türkçeleştirildi):

// ...
{
  test: /\.(scss)$/,
  use: [{
    // CSS'i sayfaya enjekte eder
    loader: 'style-loader'
  }, {
    // CSS'i CommonJS modüllerine çevirir
    loader: 'css-loader'
  }, {
    // PostCSS eklentilerini çalıştırır
    loader: 'postcss-loader',
    options: {
      // postcss 8.x için postcssOptions gerekir; postcss 7.x kullanıyorsanız bu anahtarı atlayın
      postcssOptions: {
        plugins: function () {
          return [
            require('autoprefixer')
          ];
        }
      }
    }
  }, {
    // Sass'ı CSS'e derler
    loader: 'sass-loader'
  }]
}
// ...

Kuraldaki yorumlar her yükleyicinin görevini anlatır: sass-loader Sass'ı CSS'e derler, postcss-loader Autoprefixer gibi PostCSS eklentilerini çalıştırır, css-loader CSS'i CommonJS modüllerine çevirir, style-loader da sonucu sayfaya enjekte eder. PostCSS eklentilerini isterseniz ayrı bir postcss.config.js dosyasına da taşıyabilirsiniz. Değişken ezmenin hangi sırayla yapılması gerektiği, map'ler ve yalnızca gereken Sass parçalarını derlemek Sass ile özelleştirme yazısında anlatılıyor.

Derlenmiş CSS'i içe aktarmak

Özelleştirme gerekmiyorsa Sass ile hiç uğraşmadan hazır CSS'i giriş dosyanıza ekleyebilirsiniz. Bu durumda sass-loader gerekmez; mevcut CSS kuralınız, yani style-loader ve css-loader yeterlidir:

import 'bootstrap/dist/css/bootstrap.min.css';

// ...
module: {
  rules: [
    {
      test: /\.css$/,
      use: [
        'style-loader',
        'css-loader'
      ]
    }
  ]
}
// ...

Kendi Sass dosyanızın içeriği

Sass sayfasındaki dosya yapısında projenizin kendi scss/custom.scss dosyası olur, Bootstrap ise node_modules/bootstrap altında js ve scss klasörleriyle durur. Belgelerin temel kuralı Bootstrap'in çekirdek dosyalarını değiştirmemek, bunun yerine onları içe aktaran kendi dosyanızı yazmaktır. Değişken ezmeleri fonksiyonlar içe aktarıldıktan sonra, kalan dosyalardan önce gelir. Belgelerdeki örnek <body> arka planını ve metin rengini şöyle değiştirir:

// Zorunlu
@import "../node_modules/bootstrap/scss/functions";

// Varsayılan değişkenleri ezin
$body-bg: #000;
$body-color: #111;

// Zorunlu
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";

// İsteğe bağlı bileşenler
@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// vb.

Bu dosyayı Webpack kuralındaki sass-loader derler. Bootstrap'in tamamını almak isterseniz tek satırlık @import "../node_modules/bootstrap/scss/bootstrap"; de yeterlidir; parça parça almak dosya boyutunu küçültür ama bileşenler arasındaki bağımlılıklara dikkat etmenizi gerektirir.

Eklentileri tek tek yüklerken bağımlılıklar

JavaScript sayfası js/dist/*.js dosyalarının UMD biçiminde olduğunu, bu yüzden Webpack veya Rollup gibi paketleyicilerle doğrudan kullanılabildiğini söyler. Ancak bazı eklentiler ve CSS bileşenleri başka eklentilere bağlıdır; eklentileri tek tek yüklüyorsanız bu bağımlılıkları ilgili bileşenin belgesinden kontrol etmeniz gerekir. Açılır menü, popover ve tooltip ayrıca Popper'a bağlıdır. Örneğin navbar'ın daralıp açılan menüsü Collapse eklentisini kullanır; navbar için yalnızca Dropdown'ı içe aktarırsanız menü düğmesi çalışmaz.

Parcel ile kullanım

Parcel sayfası da aynı başlangıçla açılır: Parcel'i kurar, Bootstrap'i npm ile ekler ve Popper'ı npm install @popperjs/core ile tamamlarsınız. Belgelerdeki örnek proje yapısında kaynak dosyalar src/, özel Sass dosyası scss/custom.scss, derleme çıktısı ise build/ klasöründe durur. JavaScript'i src/index.js içinde tümüyle (import * as bootstrap from 'bootstrap') ya da yalnızca gereken eklentilerle içe aktarırsınız. Sass tarafında scss/custom.scss dosyanız Bootstrap'in Sass dosyalarını içe aktarır ve yerleşik değişkenleri ezer.

Aşağıda belgelerdeki adımları bir araya getiren küçük bir örnek var. Sayfada tek bir tooltip düğmesi bulunuyor; index.js derlenmiş CSS'i ve yalnızca Tooltip eklentisini içe aktarıp sayfadaki tooltip'leri başlatıyor. Tooltip'ler performans nedeniyle isteğe bağlı olduğundan bu başlatma kodunu sizin yazmanız gerekir; döngü, tooltip belgesindeki başlatma kodunun içe aktarılan sınıfa uyarlanmış hâlidir.

<!doctype html>
<html lang="tr">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Parcel ile Bootstrap</title>
  </head>
  <body>
    <div class="container py-4">
      <button type="button" class="btn btn-primary" data-bs-toggle="tooltip" data-bs-placement="top" title="Parcel ile derlendi">
        Üzerime gelin
      </button>
    </div>
    <script src="./index.js"></script>
  </body>
</html>

// src/index.js
import 'bootstrap/dist/css/bootstrap.min.css';
import { Tooltip } from 'bootstrap';

// Tooltip'ler performans nedeniyle kendiliğinden başlamaz; sayfadakileri biz başlatıyoruz
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new Tooltip(tooltipTriggerEl)
})

Son adım package.json dosyasına geliştirme ve derleme betiklerini eklemektir. Belgelerdeki betikler şunlardır:

"scripts": {
  "dev": "parcel ./src/index.html",
  "prebuild": "npx rimraf build",
  "build": "parcel build --public-url ./ ./src/index.html --experimental-scope-hoisting --out-dir build"
}

# Geliştirme sunucusu: uygulama http://127.0.0.1:1234 adresinde açılır
npm run dev

# Derleme: dosyalar build/ klasörüne yazılır
npm run build

Bootstrap'in kendi npm betikleri

"Build tools" sayfası sizin projenizi değil, Bootstrap'in kaynak deposunu derlemeyi anlatır. Kaynak kodu indirip ya da depoyu çatallayıp kök /bootstrap klasöründe npm install çalıştırdığınızda şu ana görevler kullanılabilir hâle gelir:

Belgeler bu araç setinin Bootstrap'i ve belgelerini geliştirmek için hazırlandığını, kendi projeniz için büyük olasılıkla uygun olmadığını açıkça söyler. Kendi projenizde kullanacağınız hazır bir başlangıç noktası arıyorsanız resmî twbs/bootstrap-npm-starter şablon deposu önerilir; bu depo Sass derleyicisi, Autoprefixer, Stylelint, PurgeCSS ve Bootstrap Icons içerir.

Aynı sayfa birkaç araç seçimini de açıklar. Bootstrap, Sass dosyalarını Dart Sass ile derler ve sizin de bunu kullanmanızı önerir; v4'te kullanılan Node Sass ve LibSass kullanımdan kaldırılmıştır. Dart Sass 10 basamaklık yuvarlama hassasiyeti kullanır; küçültme sırasında bu hassasiyeti düşürecekseniz tarayıcı yuvarlama sorunlarını önlemek için en az 6 basamak korumanız önerilir. Autoprefixer önekleri derleme sırasında ekler ve desteklenen tarayıcı listesini .browserslistrc dosyasından okur. RTLCSS ise derlenmiş CSS'ten sağdan sola sürümü üretir. Bağımlılık kurulumunda sorun yaşarsanız belgelerin önerisi, önceki tüm bağımlılık sürümlerini (genel ve yerel) kaldırıp npm install komutunu yeniden çalıştırmaktır.

Sık yapılan hatalar

• Popper'ı kurmamak: Popper bir peer dependency olduğu için npm install bootstrap onu getirmez. Açılır menü, tooltip ve popover için @popperjs/core paketini ayrıca kurun.
• Hem derlenmiş CSS'i hem Sass'ı içe aktarmak: Aynı kurallar iki kez pakete girer. İkisinden birini seçin.
• Değişkenleri Bootstrap'ten sonra ezmek: Sass değişkenleri !default ile tanımlıdır; kendi değeriniz Bootstrap içe aktarılmadan önce yazılmalıdır.
• Tek eklenti dosyasında adlandırılmış içe aktarım kullanmak: js/dist dosyaları varsayılan dışa aktarım kullanır; import Modal from ... biçimini kullanın.
• Node Sass ile derlemek: Belgeler Dart Sass önerir; Node Sass ve LibSass kullanımdan kaldırılmıştır.
• Bootstrap deposunun betiklerini kendi projesinde aramak: npm run dist gibi görevler Bootstrap'in kendi deposuna aittir; sizin projenizdeki betikleri siz tanımlarsınız.

Sık Sorulan Sorular

npm install bootstrap Popper'ı da kurar mı?

Hayır. Popper, paketin peerDependencies alanında tanımlıdır. Webpack ve Parcel belgeleri onu npm install @popperjs/core ile ayrıca kurmanızı ister.

Sass bilmeden npm ile Bootstrap kullanabilir miyim?

Evet. bootstrap/dist/css/bootstrap.min.css dosyasını giriş dosyanızda içe aktarırsanız Sass derleyicisine ihtiyaç duymadan derlenmiş CSS'i kullanırsınız.

Tüm eklentileri mi içe aktarmalıyım, yalnızca gerekenleri mi?

Belgeler, bir paketleyici kullanıyorsanız yalnızca kullanacağınız eklentileri içe aktarmanızı önerir; böylece kullanmadığınız bileşenlerin kodu pakete girmez.

npm install bootstrap hangi sürümü kurar?

Sürüm belirtmeden çalıştırılan komut, paketin o anki güncel sürümünü kurar ve bu sürüm 5.0.2'den yeni olabilir. Bu yazıdaki davranışı birebir istiyorsanız sürümü komutta belirtebilirsiniz; Composer örneğindeki twbs/bootstrap:5.0.2 yazımı da aynı amaca hizmet eder. Güncel sürümü kullanacaksanız o sürümün belgelerini esas alın, çünkü sonraki sürümler yeni sınıflar ve seçenekler ekledi.

Composer veya NuGet ile kurduğumda derleme gerekir mi?

Download sayfasına göre paket yöneticisi fark etmeksizin, resmî derlenmiş sürümlerle aynı sonucu almak için Sass derleyicisi ve Autoprefixer gerekir. NuGet'in bootstrap paketi CSS sürümünü, bootstrap.sass paketi ise Sass sürümünü getirir; derlenmiş CSS ile çalışacaksanız ilkini seçmeniz yeterlidir.

yarn ile npm arasında Bootstrap açısından fark var mı?

Belgeler iki paket yöneticisi için de aynı paketi gösterir: npm'de npm install bootstrap, yarn'da yarn add bootstrap. Paketin içeriği ve içe aktarma yolları aynıdır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Bootstrap öğrenme rehberi · Bootstrap CDN kurulumu · Bootstrap Sass ile özelleştirme · Bootstrap JavaScript API · Node.js kurulumu