{"id":20816082,"url":"https://github.com/arillo/silverstripe-gulp-plate","last_synced_at":"2025-05-07T12:40:48.326Z","repository":{"id":807783,"uuid":"36431443","full_name":"arillo/silverstripe-gulp-plate","owner":"arillo","description":"Boilerplate / starting-point to create a Silverstripe production theme using a gulp.js workflow.","archived":false,"fork":false,"pushed_at":"2023-01-03T19:00:55.000Z","size":4238,"stargazers_count":9,"open_issues_count":21,"forks_count":0,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-20T18:56:35.260Z","etag":null,"topics":["boilerplate-theme","css","gulp","javascript","sass","silverstripe","webpack"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arillo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-28T10:32:12.000Z","updated_at":"2019-10-04T11:43:13.000Z","dependencies_parsed_at":"2023-01-11T15:47:52.577Z","dependency_job_id":null,"html_url":"https://github.com/arillo/silverstripe-gulp-plate","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2Fsilverstripe-gulp-plate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2Fsilverstripe-gulp-plate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2Fsilverstripe-gulp-plate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2Fsilverstripe-gulp-plate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arillo","download_url":"https://codeload.github.com/arillo/silverstripe-gulp-plate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252879038,"owners_count":21818697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate-theme","css","gulp","javascript","sass","silverstripe","webpack"],"created_at":"2024-11-17T21:27:58.091Z","updated_at":"2025-05-07T12:40:48.306Z","avatar_url":"https://github.com/arillo.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Silverstripe Gulp-plate\n\nBoilerplate / starting-point to create a [SilverStripe](https://github.com/silverstripe) production theme using a [gulp.js](http://gulpjs.com/) workflow.\n\nIncludes the following tools, tasks, and work-flows:\n\n- [Webpack](https://webpack.js.org/) as JavaScript module bundler\n- [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) for live reloading (in memory compilation for faster rebuilds while developing)\n- [ES2015](http://www.ecma-international.org/ecma-262/6.0/) syntax transpiled with [Babel](https://babeljs.io/)\n- [ESLint](http://eslint.org/) for JavaScript linting\n- [Prettier](https://prettier.io/) for JavaScript code formatting\n- [SASS](http://sass-lang.com/) compiled with libsass, [source maps](https://github.com/sindresorhus/gulp-ruby-sass#sourcemap), [autoprefixer](https://github.com/sindresorhus/gulp-autoprefixer) and [Sass linting](https://github.com/sasstools/sass-lint)\n- [BrowserSync](http://browsersync.io) for live reloading and static server\n- [svgo](https://github.com/svg/svgo) for SVG compression.\n- [gulp-svg-symbols](https://github.com/Hiswe/gulp-svg-symbols) to generate a SVG icon sprite with `\u003csymbol\u003e` \u0026 `\u003cuse\u003e` tags\n\nLooking for the static version? [Look here](https://github.com/arillo/gulp-plate).\n\n## Dependencies / Installation\n\nGulp-plate depends on the following technologies:\n\n- [node.js](http://nodejs.org) as local host environment for gulp (v. 7.5.0 or higher) [1]\n- [gulp](http://gulpjs.com/) as task-runner\n- [yarn](https://yarnpkg.com) as dependency manager\n\n[1] It is recommended to install node trough [nvm](https://github.com/creationix/nvm) (Node Version Manager).\n\nTo get started:\n\n```bash\n# In myProject `themes` folder\n$ git clone https://github.com/arillo/gulp-plate source_myTheme\n$ cd source_myTheme\n$ rm -r .git    # Remove the link to the git repo\n$ yarn          # Install dependencies\n```\n\n**Important:**\n\nPrefix your theme name with `source_`. For a source folder named `source_myTheme` a production theme with the name `myTheme` will be created. After compiling your folder structure should look like this:\n\n```bash\nmyProject\n#...\n  themes/\n    myTheme/ # Put this on the server after running the prod task. Should be ignored in `.gitignore`\n    source_myTheme/ # Holds your source files and gulp tasks\n```\n\n## Commands\n\n```bash\n$ yarn run build\n```\n\nRun the default task and generate a dev version of the site in the `dist` folder.\n\n```bash\n# Equivalent\n$ yarn start\n$ yarn run watch\n```\n\nRun the default task once, start a server and watch for file changes. See below to learn how to customize the proxy.\n\n```bash\n$ yarn run prod\n```\n\nSet `NODE_ENV='production'` and generate a production version of the site by compressing js, css \u0026 html. This is the folder that should go on the server.\n\nIf you want to run any other gulp task just append the task name to the build /gulp command:\n\n```bash\n# Equivalent\n$ yarn run build sprite\n$ yarn run b sprite\n$ yarn run gulp sprite\n$ yarn run g sprite\n```\n\n**Important:**\n\nEvery time you run build / watch / prod the generated theme directory will be deleted. Don't make any changes in that directory.\n\n## Folder structure\n\n```bash\nsource_myTheme/\n  gulpfile.js/  # gulp tasks\n  src/\n    icons/      # SVG files to be included in he the sprite\n    images/     # other images\n    js/         # js code\n    sass/       # Sass code, SCSS and Sass indented syntax possible\n    templates/  # Silverstripe templates\n```\n\n## Configuration\n\nAll paths and plugin settings have been abstracted into a centralized file: `./gulpfile.js/config.js`. Adapt the paths and settings to the structure and needs of your project.\n\n## Setting the proxy domain for browserSync\n\nBy default browserSync will use the proxy domain `php7.test` to modify the domain you can create a file named `config-local.js`. The file should export a object containing a `proxy` key with your local domain as a value:\n\n```js\n// ./gulpfile.js/config-local.js\nmodule.exports = {\n  proxy: 'local-domain.dev',\n};\n```\n\n## Symlink theme folders (SilverStripe 4)\n\nTheme folders need to be symlinked in the `public/resources/themes/\u003cyour-theme-name\u003e/` folder for the theme to work, run:\n\n```\ncd public/resources/themes/\u003cyour-theme-name\u003e/\n```\n\nand link each folder in the theme (replace `css` with the folder name you want to link):\n\n```\nln -s ../../../../themes/\u003cyour-theme-name\u003e/css css\n```\n\n## SVG Sprite configuration\n\nThe sprite creates an image with the name `sprite.svg` in `./dist/images/`. It also creates a Sass file named: `_sprite.scss` in `./src/sass/base/`.\n\nThe generated Sass files contains useful information about the sprite icons like the dimensions of each icon. The file will change every time an icon is added, removed or changed, do not edit it manually. You can change the file by changing the template in `./gulpfile.js/tpl/_sprite.scss`.\n\n## Static assets\n\nTo move static assets from the source directory without transformations, e.g. font files. Add the `src` and `dest` paths to the `static` array in the `config.js`\n\n## Sass\n\nSass indented syntax is used by default. The main Sass files need to have a `.sass` extension, otherwise the compiler fails. Partials can be both `.sass` and `.scss`.\n\n### Include external vendor css files\n\nTo include third-party styles in your css use include them in the `main.sass` file:\n\n```sass\n// main.sass\n\n@import url('../../node_modules/normalize.css/normalize.css');\n```\n\nA postcss plugin will then inline the files preserving the source-maps. After the Sass compilation.\n\nBeware that Sass will move `@import url(...)` statements to the top of the generated CSS file, so independently of the place of inclusion these styles will always be included at the top of the file.\n\n### Sass-lint errors\n\nAt the time of writing `sass-lint` fails when it encounters empty selectors. This is a [bug](https://github.com/sasstools/sass-lint/issues/456), it can be prevented by adding a indented comment `//` after the empty selector:\n\n```sass\n.mySelector\n  //\n\n.mySelector_child\n  text-align: center\n```\n\n## JavaScript\n\nThe `./gulpfile.js/config.js` file contains the full webpack configuration (see the `js` variable). Feel free to alter is as needed. Keep in mind that the `babel-loader` should always be present as `eslint` will rely on it.\n\nThere configuration will be slightly altered depending on the task you are running. When using the watch task, Javascript compilation will happen in memory, so no files are written to disk (`./dist/js/` will be empty) and `webpack-hot-middleware/client` will be injected in all bundles for live reloading to work. When building for production `webpack.optimize.UglifyJsPlugin` is used for minification. Take a look at `./gulpfile.js/util/getWebpackConfig.js` to see exactly what is happening and change it as needed.\n\nHere are some useful recipes to get you up and running:\n\n### Declare aliases for frequently required files\n\n```js\n// gulpfile.js/config.js\n\nconst js = {\n  resolve: {\n    extensions: ['.js'],\n    alias: {\n      // Path relative to `context`\n      myModule: './myModule/myModule.js',\n    },\n  },\n};\n```\n\n```js\n// src/js/some-file.js\n\nimport myModule from 'myModule';\n\nmyModule();\n```\n\nDocs: https://webpack.js.org/configuration/resolve/#resolve-alias\n\n### Shimming non CommonJs modules\n\n#### jQuery plugin\n\n```js\n// gulpfile.js/config.js\n\nconst webpack = require('webpack');\n//...\nconst js = {\n  plugins: [\n    // Make jQuery global, expected by the plugin.\n    new webpack.ProvidePlugin({\n      'window.jQuery': 'jquery',\n    }),\n  ],\n  //...\n  resolve: {\n    // Add extensions to prevent linting errors.\n    extensions: ['.js', '.json'],\n    // Path from `node_modules`, where `myModule` is the module name.\n    alias: {\n      myModule: 'myModule/dist/myModule.js',\n    },\n  },\n};\n```\n\n```js\n// src/js/main.js\n\nimport $ from 'jquery';\nimport 'myModule';\n\n$('.js-selector').myModule();\n```\n\n#### Regular JavaScript module\n\n```js\n// gulpfile.js/config.js\n\nconst js = {\n  //...\n  resolve: {\n    // Add extensions to prevent linting errors.\n    extensions: ['.js', '.json'],\n    // Path from `node_modules`, where `myModule` is the module name.\n    alias: {\n      myModule: 'myModule/dist/myModule.js',\n    },\n  },\n  module: {\n    rules: [\n      // ...\n      {\n        include: require.resolve('myModule/dist/myModule.js'),\n        loader: 'exports-loader?MyModule',\n      },\n    ],\n  },\n};\n```\n\n```js\n// src/js/main.js\n\nimport $ from 'jquery';\nimport MyModule from 'myModule';\n\nconst myInstance = new MyModule();\n```\n\nDocs: https://webpack.js.org/guides/shimming/\n\n### Multiple JavaScript bundles \u0026 vendor code sharing\n\nTo create multiple bundles add entires to `entry`\n\n```js\n// gulpfile.js/config.js\n\nconst js = {\n  // ...\n  entry: {\n    main: ['./main.js'],\n    other: ['./someFile.js', './sotherOtherFile.js'],\n  },\n  // ...\n};\n```\n\nThis will generate two bundles: `main.js` \u0026 `other.js`.\n\nIf you do this it is probably a good idea to generate another bundle that contains all shared vendor code:\n\n```js\n// gulpfile.js/config.js\n\nconst webpack = require('webpack');\n//...\nconst js = {\n  // ...\n  entry: {\n    main: ['./main.js'],\n    other: ['./someFile.js', './sotherOtherFile.js'],\n    // List vendor modules here:\n    vendor: ['jquery', 'svg4everybody'],\n  },\n  // ...\n  plugins: [\n    new webpack.optimize.CommonsChunkPlugin({\n      name: 'vendor', // Specify the common bundle's name\n    }),\n  ],\n  // ...\n};\n```\n\nDocs: https://webpack.js.org/guides/code-splitting-libraries/\n\n## Roadmap\n\n- [ ] Research Tree-shaking with webpack and implement if possible\n\n## Credits\n\nGulp-plate is based on https://github.com/greypants/gulp-starter\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farillo%2Fsilverstripe-gulp-plate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farillo%2Fsilverstripe-gulp-plate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farillo%2Fsilverstripe-gulp-plate/lists"}