npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

bretzel

v4.1.0

Published

Base de départ pour des projets HTML / CSS / JS dans un environnement de développement Node.js, Gulp et KNACSS

Downloads

7

Readme

Bretzel

Choucroute, knacks, et picon bière

Bretzel (Bretzel Project Starter) est une base de départ pour des projets HTML / CSS et JS créée par l'agence Alsacréations.

Bretzel est configuré pour fonctionner dans un environnement axé sur les outils Gulp, Sass et KNACSS (v7). Des connaissances minimales de ces outils sont un pré-requis.

Fonctionnalités

  • CSS / Sass :
    • compilation Scss vers CSS
    • ajout automatiques de préfixes CSS3 (Autoprefixer configuré via Browserslist)
    • réordonnement des propriétés (csscomb)
    • réindentation du code (beautify)
    • minification (csso), avec sourcemaps (en environnement de prod, voir ci-dessous)
  • HTML :
    • possibilité de réaliser des include de fichiers avec gulp-html-extend, voir src/home.html
  • images :
    • optimisation des images .png, .jpg, .gif, .svg (imagemin)
  • scripts :
    • rassemblements des JS projet et des JS "vendor" dans le même dossier
    • transpilation avec Babel pour profiter des syntaxes EcmaScript récentes
    • concaténation des fichiers (concat) en environnement de prod (voir ci-dessous)
    • minification (uglify) en environnement de prod
  • copie automatique des fichiers favicon.ico, .htaccess et autres fichiers .txt présents à la racine
  • possibilité de créer automatiquement une archive .zip de build ou de production
  • workflow intelligent : les tâches ne sont exécutées que pour les fichiers modifiés ou ajoutés (HTML, PHP, images, fontes)
  • intégration de KNACSS, la feuille de style de départ de tout bon projet
  • intégration Schnaps.it (template HTML basique)
  • actualisation automatique du navigateur (browsersync)
  • fichier de styleguide (guide de styles) généré sur demande
  • fichiers de documentation des fonctions JavaScript
  • fichier .editorconfig permettant d'assurer une cohérence dans les conventions d'indentations
  • fichier .sass-lint.yml de configuration pour outils de Linter .scss

Par où commencer

Choisissez un distributeur de Bretzels

Récupérez ce repo :

Prenez une Bretzel

Au sein de votre dossier de projet :

  • lancez npm install ou yarn pour installer les plugins et dépendances nécessaires (notamment KNACSS et jQuery),
  • lancez une première fois la tâche gulp pour générer le dossier de destination /dist.

En production, npm install --production n'installera que les dépendances requises et non les dépendances de développement local (devDependencies).

Mangez votre Bretzel

Au choix :

  • compilez vos fichiers avec gulp pour les tâches de base,
  • surveillez les changements de fichiers dans votre projet avec gulp watch,
  • créez le guide de styles avec gulp styleguide.

Tâches Gulp

Tâches principales

  • gulp : tous les fichiers de /src sont compilés dans /dist et ne sont ni minifiés ni concaténés. Le client peut modifier, améliorer et mettre en prod lui-même. (gulp est alias de gulp build)
  • gulp --prod : tous les fichiers de /src sont compilés dans /dist et sont - en plus - concaténés, minifiés, optimisés. Le client utilise tel quel ou doit recompiler lui-même.
  • gulp watch : surveille styles, html, php (facultatif) et scripts.

Tâches individuelles

  • gulp css : compile uniquement les fichiers Sass
  • gulp js, gulp html, gulp php, gulp img, gulp fonts : toi même tu sais
  • gulp styleguide : création d'un guide de styles
  • gulp doc-md : génère une documentation des sources JavaScript vers Markdown
  • gulp doc-html : génère une documentation des sources JavaScript vers HTML
  • gulp clean : suppression des fichiers inutiles en production
  • gulp zip et gulp zip --prod : tâche build ou prod puis création d'une archive zip. Ex. projectName-build-2017-11-22-13h37.zip ou projectName-prod-2017-11-22-13h37.zip

Gérer les dépendances

Bretzel gère les dépendances directement via npm ou yarn (pas via Bower).

Pour ajouter une dépendance, il suffit de modifier le fichier package.json ou d'utiliser les commandes npm install --save-dev :

  "dependencies": {
    "jquery": "^3.x",
    "knacss": "7.x",
    "styledown-skins": "drakeh/styledown-skins"
  },

Dans cet exemple jQuery est une dépendance npm et styledown-skins de type GitHub.

Vos dépendances JavaScript pourront être listées dans le fichier gulpfile.js sous cette forme pour être concaténées aux autres :

var vendors = [
  paths.vendors + 'jquery/dist/jquery.min.js',
  paths.vendors + 'swiper/dist/js/swiper.min.js',
  paths.src + paths.scripts.files,
  '!' + paths.src + paths.scripts.styleguideFiles, // exclusion des JS spécifiques au styleguide de la liste construite précédemment
];

.editorconfig

Les règles d'indentation (espace / tabulation) sont configurées via le fichier .editorconfig à la racine du projet.

Pour qu'elles s'appliquent, il suffit généralement de télécharger le plugin "editorconfig" dans votre éditeur.

CSS / SCSS Lint

Les fichiers Sass (.scss) de Bretzel sont rendus corrigés à l'aide d'un "linter" (outil de correction et bonnes pratiques) dont les règles sont configurées via le fichier .sass-lint.yml à la racine du projet.

L'action de correction se fera à l'aide de plugins au sein de votre éditeur HTML, ou bien d'une tâche Gulp. Par exemple, sur l'éditeur Atom, les plugins nécessaires sont Atom Linter et Atom Sass Lint.

Note : les warning subsistants dans le linter, sont connus et éventuellement à corriger selon les projets au cas par cas.

Architecture Bretzel

Voici comment est architecturé bretzel par défaut, mais rien ne vous empêche de modifier cette structure en changeant les variables présentes dans gulpfile.js :

Structure-type de l'arborescence des fichiers de bretzel

Usage avec KNACSS

  • Modifiez le fichier _variables.scss dans votre dossier src/assets/css/_config (c'est une copie modifiée de ./node_modules/knacss/sass/_config/_variables.scss. Ce dernier n'est pas utlisé car il est écrasé à chaque mise à jour de KNACSS)
  • Choisissez les fichiers KNACSS à importer au sein du fichier src/assets/css/knacss.scss
  • Votre fichier de travail est styles.scss et commencera par l'import des 2 fichiers de configuration de KNACSS _config/_variables et _config/_mixins puis par @import "knacss"; (ce dernier ne réimporte pas les 2 premiers _partials ; ils y sont commentés), puis suivront vos styles perso.

Documentation

Bretzel utilise gulp-documentation basé sur http://documentation.js.org/ pour pouvoir générer une documentation au format HTML ou Markdown selon les blocs de commentaires JSDoc placés dans les fichiers JavaScript.

La syntaxe est décrite dans la documentation de documentation https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md

Avec l'éditeur Atom, le package https://atom.io/packages/docblockr est conseillé.

Changelog

Voir le Changelog

Crédits

Projet lancé par Matthieu Bousendorfer, et tenu à jour par Alsacréations.

GitIgnore Mac OSX Crap : https://github.com/github/gitignore/blob/master/Global/OSX.gitignore