Common Stencil CLI-Fallstricke und wie man sie vermeidet

Das Stencil Command Line Interface ist ein leistungsstarkes Tool, mit dem Sie eine Vorschau der Änderungen an BigCommerce-Designs in Echtzeit anzeigen und Ihre Dateien in einem komprimierten Design bündeln können, das Sie in Ihren Shop hochladen können. Es kann ein bisschen entmutigend sein, in diese Art von Entwicklung einzutauchen, wenn Sie neu bei Stencil sind.

Als Moderator in unserer Entwickler-Community habe ich festgestellt, dass Benutzer während des Installationsvorgangs häufig auftretende Fehler bemerken können. Die Integration der Stencil-Entwicklung in Ihr lokales Setup und Ihre Prozesse ist einfach, sobald wir einige häufige Fallstricke durchgespielt haben. Dieser Beitrag führt Sie durch die Entwicklung von Stencil und hilft Ihnen hoffentlich dabei, die Reibung zu verringern, die Sie bei einigen der kniffligen Teile haben könnten.

Benötige ich die Stencil CLI?

Zunächst und vielleicht am wichtigsten sollten Sie feststellen, ob Sie die Schablonen-CLI tatsächlich installieren müssen, um die gewünschten Designänderungen in Ihrem Geschäft vorzunehmen. Arbeite klug, nicht hart!

Im Folgenden finden Sie einige Szenarien, die Sie bei dieser Entscheidung unterstützen sollen.

F: Ich möchte Kunden ein paar weitere Produktdetails auf meinen Produktseiten anzeigen - wie die Garantieinformationen - und mein aktuelles Thema zeigt dies nicht nativ an. Muss ich die Stencil CLI installieren?

A: Nein! Sie können Verweise auf zusätzliche Stencil-Objekteigenschaften wie {{product.warranty}} in einer Vorlagendatei hinzufügen, ohne die CLI zu verwenden. BigCommerce verfügt über einen integrierten Editor für Designdateien, mit dem Sie die gewünschten Änderungen vornehmen können. In unserer Anleitung können Sie auf Ihre Designdateien zugreifen und Änderungen direkt in Ihrem Dashboard vornehmen.

In unserer Dokumentation finden Sie eine Liste der verfügbaren Objekte und der Teilobjekte, auf die verwiesen werden kann. (Vergessen Sie nicht, neue Objekte in einer Vorlage mit Frontmaterie zu deklarieren.)

F: Muss ich die Stencil-CLI installieren, um meinen Shop in weitere Sprachen zu übersetzen?

A: Ja, dies ist eine Situation, in der Sie die CLI installieren müssen, da Sie eine neue json-Übersetzungsdatei hinzufügen und diese in das Design einbinden müssen.

F: Ich möchte für bestimmte Produkte ein benutzerdefiniertes Seitenlayout erstellen. Brauche ich dazu die CLI?

A: Ja, zum Erstellen einer benutzerdefinierten Vorlagendatei muss Stencil CLI installiert werden. Sie benötigen die CLI, um während der Arbeit eine Vorschau der benutzerdefinierten Vorlage mit Ihrer Produktseite anzuzeigen und die neue Datei mit Ihrem Thema zu bündeln.

Installieren der CLI

Wir haben eine einfache Anleitung für die Installation der CLI hier im BigCommerce Dev Center, aber ich möchte einige Punkte während des Installationsprozesses ansprechen, bei denen die Leute stecken bleiben.

Abhängigkeiten mit Git und npm installieren

Mir ist aufgefallen, dass Windows-Benutzer manchmal in eine Sackgasse geraten, wenn es darum geht, Stencil und seine Abhängigkeiten von npm abzurufen. Dazu benötigen Sie ein Shell-Befehlszeilentool, mit dem Unix-Befehle ausgeführt werden können. In unserer Dokumentation empfehlen wir Git Bash, Sie können jedoch Powershell oder eine andere Software verwenden.

Sobald Sie Node mit den zum Ausführen von Stencil erforderlichen Abhängigkeiten installiert haben, können Sie den Befehl npm verwenden.

Anpassen eines vorhandenen Themas

In unserer Dokumentation empfehlen wir Ihnen, die neueste Version von Cornerstone von GitHub herunterzuladen. Dies ist jedoch nicht erforderlich, wenn Sie bereits ein Thema haben, an dem Sie Änderungen vornehmen möchten.

In diesem Szenario müssen Sie lediglich Ihr Design vom BigCommerce-Dashboard herunterladen. Klicken Sie unter Storefront> Meine Designs auf Aktuelles Design herunterladen, um eine Zip-Datei Ihres Designs herunterzuladen.

(Hinweis: Für Pixel Union-Designs müssen Sie vor diesem Schritt BitBucket-SSH-Schlüssel einrichten.)

Als nächstes entpacken Sie es und navigieren in Ihrer Shell zum Themenverzeichnis

cd / files / my_theme

Dann renne

npm install

Beachten Sie die Abhängigkeitsversionen

Das größte Problem, das bei der Installation der Stencil-CLI aufgetreten ist, besteht darin, dass Benutzer nicht die empfohlene Version von Node oder Python oder nicht die neueste Version der CLI selbst verwenden.

Wenn Sie die CLI vor einiger Zeit heruntergeladen haben, ist jetzt ein guter Zeitpunkt, um die neueste Version zu installieren. Um sicherzustellen, dass dies reibungslos funktioniert, führen Sie es aus

npm uninstall -g @ bigcommerce / stencil-cli

dann

npm installiere -g @ bigcommerce / stencil-cli

Dadurch wird die CLI global deinstalliert und erneut installiert.

Mit Node haben wir die Versionen 6.10.3 bis 8.12.0 getestet. Wenn Sie eine frühere oder spätere Version verwenden, wird beim Ausführen von stencil init möglicherweise ein solcher Fehler angezeigt - zusätzlich zu einer Fülle lustiger Warnungen.

Schwerwiegender Fehler: Die Datei "sass / context.h" wurde nicht gefunden

Okay, was jetzt? Nuke zunächst den Ordner "Node modules".

rm -rf node_modules

Führen Sie nun nvm install 7.6.0 aus

Nachdem die unterstützte Version erfolgreich installiert wurde, führen Sie nvm mit 7.60 aus, und überprüfen Sie, ob Sie es verwenden, indem Sie Knoten -v ausführen. Sie sollten nun sehen, dass Sie die unterstützte Version verwenden

Jetzt mit Node v7.6.0 (npm v6.8.0)

Führen Sie schließlich npm install in Ihrem Designverzeichnis aus, und Sie sollten in der Lage sein, alle Knotenmodule erfolgreich zu installieren. Wenn Sie stencil init ausführen, sollten keine Fehler angezeigt werden. Wenn Sie bereit sind, mit der Entwicklung zu beginnen, starten Sie die Schablone!

Häufig gestellte Fragen

F: Beim Ausführen von npm install wird ein Fehler angezeigt: npm ERR! Versuchen Sie erneut, diesen Befehl als root / Administrator auszuführen.

A: Sie möchten versuchen, einen npm-Cache als Administrator zu bereinigen:

sudo cache clean -f

Führen Sie dann npm installagain aus.

F: Beim Ausführen von stencil init wird ein 500-Fehler angezeigt. Liegt dies an einem Fehler von BigCommerce?

A: Es gibt ein paar Dinge zu überprüfen, wenn dies passiert:

  • Stellen Sie sicher, dass Sie eine empfohlene Version von Node verwenden
  • Dieser Fehler wird angezeigt, wenn in Ihrem BigCommerce Store kein Stencil-Design angewendet wurde.
  • Dies kann ein Nebeneffekt sein, wenn Sie über einen Proxy-basierten Domänendienst wie Cloudflare oder Amazon Cloudfront eine Anfrage an einen Shop stellen. Wenn Sie den Verdacht haben, dass dies der Schuldige ist, ändern Sie die Hosts-Datei auf Ihrem Computer, um Ihren Localhost der BigCommerce-IP Ihres Geschäfts zuzuordnen.

F: Ich konnte Stencil installieren und einrichten, es wird jedoch ein 404-Fehler angezeigt, wenn ich versuche, eine Vorschau einer benutzerdefinierten Vorlagendatei anzuzeigen.

A: Der Grund für diese Fehlermeldung ist, dass Sie zuerst eine entsprechende Seite in Ihrem Live-Shop mit derselben URL erstellen müssen, der Sie die benutzerdefinierte Vorlage in Ihrer .stencil-Datei zugeordnet haben. Angenommen, Sie haben die .stencil-Datei bereits so bearbeitet, dass sie einen Schlüssel für eine benutzerdefinierte Produktvorlage enthält:

"Produkt": {
"Alternate-product.html": "/ test-url /"
}

Sie müssen sich im Control Panel Ihres BigCommerce-Shops anmelden und ein Produkt mit der URL / test-url / erstellen.

Abschließende Gedanken

Sobald Sie den Installationsvorgang abgebrochen haben, ist die Problembehandlung für jeden Schritt viel einfacher. Wenn Sie immer noch verloren sind, ein bestimmtes Setup haben oder einfach mit anderen Entwicklern über die erweiterte Stencil-Entwicklung sprechen möchten, wenden Sie sich an die Entwickler-Community. Haben Sie ein interessantes Stencil-Projekt, an dem Sie arbeiten? Tweet @BigcommerceDevs - wir möchten davon hören!