Özel şablon oluşturun

IDX, kullanıcıların bir dili veya çerçeveyi hızlıca kullanmaya başlamak için ihtiyaç duyabileceği tüm dosyaları, sistem paketlerini (ör. derleyiciler) ve uzantıları içeren çok çeşitli yerleşik şablonlar sunar.

Kullanıcı tarafından yapılandırılabilen kendi şablonlarınızı da oluşturmak isteyebilirsiniz. Örneğin:

• Kendi çerçevenizi, kitaplığınızı veya hizmetinizi oluşturuyorsanız kullanıcılarınızın tarayıcıdan ayrılmadan, bulut tabanlı bir sanal makinenin tüm gücünden yararlanarak teknolojinizi hızla kullanmaya başlamasını sağlayabilirsiniz.

• Projeleriniz için tercih edilen bir teknoloji yığınınız varsa özel bir şablonla yeni projeler başlatmak için kendi sürecinizi basitleştirebilirsiniz.

• Başkalarına (ör. codelab aracılığıyla) eğitim veriyorsanız codelab'inizin başlangıç noktasını özel bir şablon olarak önceden yapılandırarak öğrencilerinizin başlangıç adımlarından bazılarını kaldırabilirsiniz.

Hazır bir özel şablon oluşturduktan sonra web sitenize, Git deposu README dosyasına, paket ayrıntıları sayfasına (ör. NPM'de) veya kullanıcıların teknolojinizi kullanmaya başlamak isteyebilecekleri diğer yerlere yerleştirebileceğiniz bir bağlantı oluşturabilirsiniz.

Not: Dilerseniz Git deposunu klonlayarak kullanıcıların yeni bir çalışma alanı oluşturabileceği bir bağlantı da oluşturabilirsiniz. Bu kod, kendi IDX şablonunuzu oluşturmaya kıyasla daha az yapılandırılabilir ancak Git deposunda değişiklik gerektirmez.

Ön koşullar

Başlamadan önce, ortamınızı .idx/dev.nix dosyalarıyla özelleştirme hakkında bilgi sahibi olduğunuzdan emin olun.

Şablonlar Nix dilini de kullanır. Bu nedenle, bazı temel bilgileri tazelemek veya referans olarak kullanmak isteyebilirsiniz.

Şablon dosya yapısı

Şablon, en az iki dosya içeren herkese açık bir GitHub deposudur (veya kod deposundaki klasör ya da daldır):

• 

  Özel şablondan yeni çalışma alanı oluşturma

  idx-template.json, şablonun kullanıcı tarafından görülebilen adı, açıklaması ve şablonu yapılandırmak için kullanabileceği parametreler dahil olmak üzere şablonun meta verilerini içerir. Örneğin, kullanıcılarınıza çeşitli programlama dilleri veya örnek kullanım alanları arasından seçim yapma olanağı sunabilirsiniz. IDX, şablonunuzdan yeni bir çalışma alanı oluşturmayı seçtiklerinde kullanıcılara gösterilen kullanıcı arayüzünü hazırlamak için bu bilgileri kullanır.

• idx-template.nix, Nix dilinde yazılmış ve aşağıdakilerden sorumlu olan Bash kabuk komut dosyasını (nix işleviyle sarmalanmış) içeren bir dosyadır:

  1. Yeni çalışma alanının çalışma dizinini oluşturma ve
  2. .idx/dev.nix dosyası oluşturarak ortamını ayarlama. Bu komut dosyasında flutter create veya npm init gibi bir proje iskelesi aracını ya da Go, Python, Node.js veya başka bir dilde yazılmış özel bir komut dosyası çalıştırabileceğinizi unutmayın.

  Bu dosya, şablonu yapılandırırken kullanıcı tarafından belirtilen parametrelerle yürütülür.

Şablonun somutlaştırılması amacıyla idx-template.nix içinde kullanılmak üzere bu iki dosyanın yanına başka dosyalar eklenebilir. Örneğin, son .idx/dev.nix dosyasını dahil edebilir, hatta tüm iskele dosyalarını doğrudan depoya ekleyebilirsiniz.

Temel bir örnek: Herkese açık herhangi bir GitHub deposunu şablona dönüştürme

idx-template.json ve idx-template.nix öğelerini nasıl tanımlayacağınıza dair ayrıntılara inmeden önce, şu özelliklere sahip temel bir örnek şablon incelemenizi öneririz:

• Kullanıcı tarafından yapılandırılabilen parametre yok
• Şablon deponuzdaki tüm dosyaları (iki idx-template dosyası hariç) kullanıcının çalışma alanına kopyalar. Ortamı tanımlayan dev.nix dosyasına sahip bir .idx alt klasörü olmalıdır.

Aşağıdaki dosyaları herkese açık bir GitHub deposuna (veya alt klasöre ya da brana) eklediğinizde bu kod deposu etkili bir şekilde IDX şablonuna dönüştürülür.

idx-template.json

{
  "name": "Hello world",
  "description": "A template for a CLI program that prints 'hello world'",
  "icon": "https://www.gstatic.com/images/branding/productlogos/idx/v1/192px.svg",
  "params": []
}

idx-template.nix

# No user-configurable parameters
{ pkgs, ... }: {
  # Shell script that produces the final environment
  bootstrap = ''
    # Copy the folder containing the `idx-template` files to the final
    # project folder for the new workspace. ${./.} inserts the directory
    # of the checked-out Git folder containing this template.
    cp -rf ${./.} "$out"

    # Set some permissions
    chmod -R +w "$out"

    # Remove the template files themselves and any connection to the template's
    # Git repository
    rm -rf "$out/.git" "$out/idx-template".{nix,json}
  '';
}

Not: $out dışında, yeni çalışma alanının kimliğini de $WS_NAME kullanarak da alabilirsiniz.

bootstrap komut dosyanızda ek sistem paketleri kullanın

Önceki örnekte, dosyaları doğru yere kopyalamak için yalnızca temel POSIX komutları kullanılmaktadır. Şablonunuzun bootstrap komut dosyası, git, node, python3 veya diğerleri gibi ek ikili programların yüklenmesini gerektirebilir.

idx-template.nix dosyanızda packages öğesini belirterek önyükleme komut dosyanıza ek sistem paketlerini sunabilirsiniz. Tıpkı dev.nix dosyasındaki packages öğesine ekleyerek çalışma alanını ek sistem paketleriyle özelleştirmeniz gibi.

Not: idx-template.nix her zaman stable-23.11 Nix kanalını kullanır.

node, npx ve npm gibi ikili programları içeren pkgs.nodejs ekleme örneğini aşağıda bulabilirsiniz:

# idx-template.nix
{pkgs}: {
  packages = [
    # Enable "node", "npm" and "npx" in the bootstrap script below.
    # Note, this is NOT the list of packages available to the workspace once
    # it's created. Those go in .idx/dev.nix
    pkgs.nodejs
  ];

  bootstrap = ''
    mkdir "$out"
    # We can now use "npm"
    npm init --yes my-boot-strap@latest "$out"
  ''
}

Önemli: Önyükleme komut dosyanız etkileşimli olamaz. Kullanıcı girişini beklerse şablon doğru bir şekilde örneklenemez.

Kullanıcı tarafından yapılandırılabilen parametreler ekleme

Kullanıcıların yeni projelerinin başlangıç noktasını özelleştirmesine izin vermek için birden fazla şablon veya parametrelerle tek bir şablon oluşturabilirsiniz. Farklı başlangıç noktalarınız sadece bir CLI aracına iletilen farklı değerlerse (örneğin, --language=js ve --language=ts) bu mükemmel bir seçenektir.

Parametre eklemek için:

1. Parametrenizi, idx-template.json meta veri dosyanızın params nesnesinde açıklayın. IDX, şablonunuzun kullanıcılarına gösterilen kullanıcı arayüzünü (onay kutuları, açılır menüler ve metin alanları gibi) hazırlamak için bu dosyadaki bilgileri kullanır.
2. idx-template.nix önyüklemenizi, şablonu örneklendirirken kullanıcının seçtiği değerleri kullanacak şekilde güncelleyin.

idx-template.json içindeki parametrenizi açıklayın

IDX'in, seçeneklerin sayısına bağlı olarak açılır menü veya radyo düğmesi grubu olarak gösterildiği bir enum parametresi eklemeyle ilgili bir örneği aşağıda bulabilirsiniz:

{
  "name": "Hello world",
  "description": "A hello world app",
  "params": [
    {
      "id": "language",
      "name": "Programming Language",
      "type": "enum",
      "default": "ts",
      "options": {
        "js": "JavaScript",
        "ts": "TypeScript"
      },
      "required": true
    }
  ]
}

İki değer (JavaScript ve TypeScript) olduğundan, kullanıcı arayüzü iki seçenek için bir radyo düğmesi grubu oluşturur ve idx-template.nix komut dosyasına ts veya js değerini iletir.

Her parametre nesnesi aşağıdaki özelliklere sahiptir:

MÜLK	TÜR	AÇIKLAMA
id	string	Parametrenin, değişken adına benzer benzersiz kimliği.
ad	string	Bu parametrenin görünen adı.
tür	string	Bu parametre için kullanılacak kullanıcı arayüzü bileşenini ve önyükleme komut dosyasına aktarılacak veri türünü belirtir. Valid values are: "enum" - Bir açılır liste veya radyo düğmesi grubu gösterir ve önyüklemeye bir string iletir "boolean" - Bir onay kutusu gösterir ve true veya false geçer "text" - Bir metin alanı gösterir ve bir string iletir
seçenekler	object	enum parametreleri için bu, kullanıcılara gösterme seçeneklerini temsil eder. Örneğin, seçenekler {"js": "JavaScript", ...} ise seçenek olarak "JavaScript" gösterilir. Seçildiğinde bu parametrenin değeri js olur.
varsayılan	string veya boolean	Kullanıcı arayüzündeki başlangıç değerini ayarlar. enum parametreleri için bu, options içindeki anahtarlardan biri olmalıdır. boolean parametreleri için bu değer true veya false olmalıdır.
zorunlu	boolean	Bu parametrenin gerekli olduğunu gösterir.

idx-template.nix öğesinde parametre değerlerini kullanın

idx-template.json dosyanızda params nesnesini tanımladıktan sonra, önyükleme komut dosyasını kullanıcının seçtiği parametre değerlerine göre özelleştirmeye başlayabilirsiniz.

Önceki bölümdeki örneğe göre, ts veya js olası değerlerine sahip language kimliğine sahip tek bir parametreniz varsa bu parametreyi şu şekilde kullanabilirsiniz:

# idx-template.nix
# Accept additional arguments to this template corresponding to template
# parameter IDs, including default values (language=ts by default in this example).
{ pkgs, language ? "ts", ... }: {
  packages = [
    pkgs.nodejs
  ];

  bootstrap = ''
    # We use Nix string interpolation to pass the user's chosen programming
    # language to our script.
    npm init --yes my-boot-strap@latest "$out" -- --lang=${language}
  ''
}

Yaygın olarak kullanılan diğer bir kalıp, dizenin değerine bağlı olarak içeriği koşullu olarak dahil etmektir. Önceki örneği yazmanın başka bir yolu da şu şekildedir:

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

Önemli: bootstrap komut dosyanızın bir parçası olarak $out dizininde her zaman .idx/dev.nix dosyası oluşturmayı unutmayın. Oluşturulan çalışma alanı ortamının, kullanıcı tarafından yapılandırılan parametrelere göre (ör. farklı sistem paketleri dahil etme veya onCreate kancasını özelleştirme) değişiklik göstermesi gerekiyorsa Nix'te dize işlemeyi kullanabilir veya jinja2 gibi bir şablon oluşturma motoruna çağrı yapabilirsiniz.

Varsayılan olarak açılacak dosyaları seçin

Şablonunuzla yeni çalışma alanları oluşturulduğunda hangi dosyaların düzenlenmek üzere açılacağını özelleştirmek iyi bir fikirdir. Örneğin, şablonunuz temel bir web sitesiyle ilgiliyse ana HTML, JavaScript ve CSS dosyalarını açmak isteyebilirsiniz.

Varsayılan olarak açılması gereken dosyaları özelleştirmek için .idx/dev.nix dosyanızı (idx-template.nix dosyanızı değil) openFiles özelliğine sahip bir onCreate çalışma alanı kancası içerecek şekilde güncelleyin. Örneğin:

# .idx/dev.nix
{pkgs}: {
  ...
  idx = {
    # Workspace lifecycle hooks
    workspace = {
      # Runs when a workspace is first created with this `dev.nix` file
      onCreate = {
        # Open editors for the following files by default, if they exist.
        # The last file in the list will be focused.
        default.openFiles = [
          "src/index.css"
          "src/index.js"
          "src/index.html"
        ];
        # Include other scripts here, as needed, for example:
        # installDependencies = "npm install";
      };
      # To run something each time the workspace is (re)started, use the `onStart` hook
    };
    # Enable previews and customize configuration
    previews = { ... };
  };
}

Şablonunuzdan yeni bir çalışma alanı oluşturun

Şablonunuzu uçtan uca test etmenin en basit yolu, şablonla yeni bir çalışma alanı oluşturmaktır. Örneği şablonunuzun GitHub deposu URL'siyle değiştirerek aşağıdaki bağlantıyı ziyaret edin:

https://idx.google.com/new?template=https://github.com/my-org/my-repo

Dilerseniz bir dal ve alt klasör de ekleyebilirsiniz. Aşağıdakilerin tümü, herkesin erişimine açık oldukları sürece geçerlidir:

• https://github.com/my-org/my-repo/
• https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplate
• https://github.com/my-org/my-repo/tree/branch
• https://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate

Bu aynı zamanda, yeni şablonunuzu kullanabilmeleri için başkalarıyla paylaşacağınız veya "IDX'te aç" düğmenizden bağlantı vereceğiniz URL'dir.

---

Şablonunuzu paylaşın

Şablonunuzun beklendiği gibi davrandığını onayladıktan sonra GitHub deposunda yayınlayın ve test için çalışma alanı oluştururken kullandığınız bağlantıyı paylaşın.

Kullanıcıların şablonunuzu bulmasını daha da kolaylaştırmak için web sitenize veya BENİOKU deposuna bir "IDX'te aç" düğmesi ekleyin.